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

Annotations already declare destructiveHint=true, so the bar is lower, yet the description still adds genuinely useful context: it modifies the analysis definition and an automatic backup is created beforehand. It omits whether the change is reversible and any permission requirements, but the backup disclosure is meaningful behavioral information beyond the annotation.

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 the purpose front-loaded and the mutation warning immediately after. Zero filler; 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?

An output schema exists, so return values need not be explained, and annotations cover the destructive nature. With full schema coverage on a four-parameter tool, the description is nearly complete, lacking only usage routing and permission 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 all four parameters (including expression syntax examples and the dataset_identifier lookup hint) are already documented in the schema. The description adds nothing about parameters, 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 (Add), resource (calculated field), and target (QuickSight analysis), which cleanly separates it from get/update/delete/list_calculated_field siblings. It stops short of explicitly naming update_calculated_field as the alternative for existing fields, so it does not fully differentiate.

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?

No statement of when to use this versus update_calculated_field, no prerequisites (e.g. required permissions), and no conditions under which it should not be used. The reader must infer that 'Add a new' implies the field does not already exist.

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

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

With no annotations, the description must carry the behavioral burden. It does disclose that this mutates the analysis definition and that a backup is created automatically before changes, which is genuinely useful. It omits permission requirements, idempotency (what happens if the FilterGroupId already exists), and failure modes.

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, front-loaded with the action and followed by the warning. Nothing is wasted, though the warning could be more tightly phrased.

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

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

An output schema exists, so return values need not be explained. However, for a mutation tool with zero annotations, the definition leaves gaps around permissions, overwrite behavior on a duplicate FilterGroupId, and failure conditions.

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 filter_group_definition description already includes a full example with required keys. The description adds no parameter-level 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 states a specific verb and resource ('Add a filter group to a QuickSight analysis'), which is unambiguous. It does not explicitly differentiate from the sibling delete_filter_group or get_filters, so it lands one notch below the top tier.

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

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

There is no guidance on when to use this versus alternatives such as delete_filter_group, nor any stated prerequisites. The only contextual note is the backup warning, which is behavior, not usage 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?

No annotations are supplied, so the description carries the full burden. It does add real value beyond the schema by flagging that the analysis definition is modified and that a backup is created automatically, which reassures the agent about recoverability. It stops short of stating the permissions required, whether the change is reversible beyond the backup, or how the parameter affects existing visuals.

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 blocks, action statement first, warning second — zero filler and the risky detail is front-loaded where an agent will see it.

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

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

The tool has an output schema and complete parameter documentation, so return values need not be explained. What remains missing is the surrounding operational context for a mutation on a live analysis definition: permission requirements and downstream effects on dependent visuals.

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

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

Schema description coverage is 100%, and the parameter_definition field already documents the four allowed declaration types plus a full worked example, so the description adds nothing about parameters. 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 (add) and resource (parameter) scoped to a QuickSight analysis, which is unambiguous on its own. It does not, however, distinguish itself from the sibling delete_parameter or explain how a parameter differs from a calculated field, which is the nearer confusion in this toolset.

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

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

The description gives no indication of when to reach for add_parameter versus add_calculated_field, add_filter_group, or the update_* siblings, and no prerequisites such as required analysis permissions or whether the analysis must be in a published/draft state. Only the mutation itself is described.

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 are empty, so the description carries the full burden. It does usefully disclose the mutation ('modifies the analysis definition') and the automatic backup, which is real behavioral value. However it omits permissions requirements, whether sheet names must be unique, and whether the operation is idempotent — gaps that matter for a mutation tool with zero 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?

Two short sentences, front-loaded with the action and followed by the risk warning. No filler. Slightly terse given the mutation risk, but structurally sound.

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

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

An output schema exists, so return values need not be explained, and the mutation risk plus automatic backup are covered. For a 2-parameter tool this is largely complete, though permission/constraint context could be richer given the absent 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% and both parameters (name, analysis_id) are documented in the schema; the description adds no format, constraint, or uniqueness details beyond that. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb+resource ('Add a new sheet to a QuickSight analysis'), which clearly distinguishes it from the delete_sheet, rename_sheet, and replicate_sheet siblings. It stops short of naming those alternatives explicitly, so it is clear but not maximally 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?

No guidance on when to add a sheet versus rename_sheet, replicate_sheet, or add_visual to an existing sheet, and no prerequisites or preconditions stated. The only contextual note is that a backup happens automatically, which is not usage guidance.

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

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

With no annotations, the description carries the full burden, and it does disclose one important trait: mutation of the analysis definition plus an automatic backup. It stops short of stating permission requirements, whether re-adding overwrites an existing visual, or failure behavior, so meaningful behavior remains undisclosed.

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

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

Two tight sentences with the warning isolated on its own line, so the destructive-by-default nature is front-loaded. Efficient and free of padding, though the warning could be slightly more precise about scope of the change.

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

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

An output schema exists, so return values need no explanation, and the schema fully covers parameters. For a mutation tool the description covers the essential safety context (backup) but omits permissions and conflict/overwrite semantics, so it is nearly complete rather than fully so.

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 in the schema, including the required dict-shape of visual_definition and the pointer to get_visual_definition. The description adds no parameter meaning beyond that, making the baseline 3 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 ('Add a visual to a sheet in a QuickSight analysis'), so the action is unambiguous. However, it does not distinguish itself from siblings that also create visuals (create_kpi, create_bar_chart, create_line_chart, add_sheet), leaving the agent to infer when the generic definition-driven path is correct.

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

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

The description gives no when-to-use guidance and never mentions the typed siblings (create_bar_chart, create_kpi, etc.) that appear to overlap. The only actionable hint about obtaining a definition lives in the schema, not the description, so the agent gets no routing help from this text.

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 carry idempotentHint, so the description does real work: it discloses that a timestamped JSON file is written, what the file contains (sheets, visuals, calculated fields, parameters, filters), and the exact destination path. It does not say whether repeated calls accumulate new files or overwrite, which is the one behavior that would matter most given the timestamped naming.

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 core action and scope, then contents, then the companion tool and destination. No filler and no repetition of the schema.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose, content, destination, and restore pairing. The remaining gap is the overwrite/timestamp-accumulation question, which is not addressed anywhere in the structured data.

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 a single parameter at 100% schema description coverage, the schema already defines analysis_id fully. The description adds no format, identifier-source, or validation detail beyond the schema, 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 ('Save a full backup of a QuickSight analysis definition to disk') and enumerates what the backup contains. It is clear about scope, though it never differentiates itself from the similarly-named sibling snapshot_analysis (or backup_dataset), leaving the agent to guess which backup-style tool applies.

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 pairs the tool with its counterpart ('Use restore_analysis to restore from a backup'), which tells the agent the intended workflow. It stops short of stating when-not-to-use it versus snapshot_analysis, so the alternative-selection guidance is incomplete.

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 idempotentHint, so the description carries most of the burden and delivers real detail: it produces a timestamped JSON file, writes to ~/.quicksight-mcp/backups/, and lists what the payload contains (SQL, columns, physical/logical table maps). It stops short of stating permission requirements or failure modes for large datasets.

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 action and outcome are front-loaded in the first sentence, followed by concise supporting detail on file format and location. Slightly padded by the parenthetical field list, but nothing 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?

For a one-parameter, low-risk tool with an output schema, the description supplies the essentials an agent needs: what is captured, the file format, and the on-disk location. It lacks only guidance on when the backup should be preferred over related read 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?

Only one parameter and schema description coverage is 100%, so the schema fully documents dataset_id. The description adds no syntax or format detail for it, which is the expected baseline 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 (save/backup) and resource (QuickSight dataset configuration) with a clear target (disk). It is distinguishable from sibling tools such as get_dataset (read), snapshot_analysis/backup_analysis (analyses, not datasets), and restore_analysis.

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

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

Usage is implied (back up a dataset before mutating it, given siblings like update_dataset_sql and update_dataset_definition), but the description never says when to use this versus get_dataset, snapshot_analysis, or backup_analysis, and names no exclusions or prerequisites.

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, so the destructive nature is covered by structured data. The description usefully adds the state precondition (QUEUED or RUNNING) and the blocking rationale, but says nothing about what happens to partially ingested data, whether the cancellation is final, or what error occurs if the ingestion is already complete or not found.

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 two short follow-up sentences that each add distinct value (state precondition, motivation). No filler or restatement of the 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?

An output schema exists, so return-value explanation is unnecessary, and parameters are fully covered by the schema. The description supplies the state and motivation context an agent needs to decide to call it; only post-cancellation behavior/error cases are absent.

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

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

Schema description coverage is 100%, so both dataset_id and ingestion_id are already documented, including the hint that ingestion_id comes from refresh_dataset or list_recent_refreshes. The description adds no parameter-level detail beyond the schema, which matches the baseline for fully covered schemas.

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 (Cancel) and resource (a running SPICE dataset refresh), scoped to the ingestion rather than the dataset definition itself. This clearly distinguishes it from siblings like refresh_dataset (which starts an ingestion) and get_refresh_status (which only reads state).

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

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

Gives explicit when-to-use conditions: ingestions stuck in QUEUED or RUNNING, and the motivating scenario where old ingestions block new ones. It does not explicitly name or compare against alternatives such as get_refresh_status or letting the ingestion finish, so it stops short of full alternative routing.

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

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

Annotations are empty, so the description carries the full burden: it discloses that the clone gets a new name and ID, lists all copied components, and states the original is unaffected. It omits permission requirements, size limits, and whether the clone counts against quotas, leaving some 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?

Front-loads the one-line purpose before the detail and workflow. The numbered workflow is slightly verbose but each step maps to a real action, so little is wasted.

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

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

An output schema exists, so return values need not be explained, and the description covers what is cloned and the intended workflow. It is complete for invocation, with only minor gaps around permissions and side effects.

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 only two required params, so the schema already documents them fully. The description reinforces that a new name is assigned but adds no format or constraint detail beyond the schema, warranting the baseline 3.

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 (clone) and resource (QuickSight analysis) plus its purpose, and elaborates exactly what is copied (sheets, visuals, calculated fields, parameters, filters). It does not explicitly distinguish itself from similar siblings such as backup_analysis or snapshot_analysis, which an agent may 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?

Provides explicit context ('test changes without affecting the original') and a numbered best-practice workflow ending in publish_dashboard and deleting the clone. No exclusions or named alternatives (e.g., vs snapshot_analysis) are given, so it is clear but not fully 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?

No annotations are provided, so the description carries the full burden. It says only 'from simple parameters' and never discloses that this is a mutating operation that adds a visual to an existing sheet, nor any permission or side-effect implications.

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 short sentence is front-loaded and not padded, but the phrase 'from simple parameters' is vague filler rather than useful information. It is concise but under-informative.

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 (7 required), an output schema, and no annotations, the description should clarify the mutation semantics and the relationship between analysis_id and sheet_id. Instead it leaves the agent to derive all of this from the schema alone.

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 80%, so the schema already documents most parameters (analysis_id, sheet_id, category/value columns, aggregation). The description adds nothing beyond the schema, 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 states a specific verb and resource (create a bar chart), which is clear on its own. However, it offers no differentiation from the many sibling chart/visual creators like create_line_chart, create_pie_chart, create_combo_chart, and add_visual.

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

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

There is no guidance on when to choose a bar chart over a line, pie, or combo chart, nor any mention of prerequisites such as the target analysis/sheet needing to exist. The agent must infer usage entirely.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says nothing about permissions, whether the chart is persisted to the sheet, error behavior for invalid column/aggregation combinations, or whether the operation is reversible/removable (e.g., via delete_visual). For a mutation tool with zero annotation coverage this is a significant gap.

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

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

Short and front-loaded: the action comes first, followed by a one-sentence clarifying definition and an example. The second sentence is borderline redundant with the parenthetical in sentence one, but it earns its place by disambiguating the 'sharing a category axis' semantics.

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

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

An output schema exists, so return values need not be described. However, for a 12-parameter, 9-required mutation tool with no annotations, the description does not cover prerequisites or constraints (e.g., that line and bar columns must be measures compatible with the aggregation, or that the sheet must belong to the given analysis). Adequate but with clear gaps.

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

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

Schema description coverage is 100% with 12 well-documented parameters, so the schema already explains columns, aggregations, and format strings. The description adds nothing about parameters beyond a vague 'from simple parameters', leaving the baseline of 3 appropriate.

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

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

The description states a specific verb and resource ('Create a combo chart') and then defines the concept as 'bars + line on same chart', which cleanly distinguishes it from the sibling create_bar_chart and create_line_chart tools. 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?

The example ('count bars with a percentage line overlay') implies a use case but there is no explicit when-to-use-this-vs-a-simple-bar-or-line-chart guidance, nor any prerequisites such as needing an existing sheet, analysis, and dataset. No exclusions or alternatives are named despite the many sibling chart creators.

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 only annotation is destructiveHint=true, and the description adds nothing about behavior beyond the annotation: it does not say whether naming collisions fail, whether the data source must be reachable, what permissions are required, or whether a refresh follows creation. For a creation tool that mutates account state, that is a significant omission.

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

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

A single, front-loaded sentence with no filler; the verb and resource come first. Nothing 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?

An output schema exists so return values need not be described, and all four parameters are documented in the schema. However, in a toolset of this size, a create tool should at least say when it applies and what it requires; the description is adequate but thin.

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 itself explains SQL validity, import_mode semantics, and how to obtain the data_source_arn. The description contributes no additional parameter 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?

States a specific verb and resource ('Create a new QuickSight dataset') plus the input source ('from a SQL query'), so the agent knows exactly what is produced. No sibling performs the same create-dataset action, but the description never distinguishes itself from adjacent tools like clone_analysis or backup_dataset.

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

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

There is no guidance on when to use this instead of update_dataset_definition, update_dataset_sql, or clone_analysis, and no prerequisites or preconditions are mentioned. The agent must infer usage purely from the name.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure but offers almost none. It implies a mutation ('Create'), yet does not state required permissions, side effects, whether the KPI is added to an existing sheet, or any failure modes.

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 sentence with no wasted preamble. While 'from simple parameters' is somewhat vague filler, the overall structure is efficient and easy to scan.

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

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

For a mutation tool with no annotations and eight parameters, the description is too thin. Although an output schema exists and the input schema is fully documented, an agent still lacks context about what a KPI visual is, where it gets placed, or what prerequisites exist beyond the schema 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?

The input schema has 100% description coverage, so the baseline is 3. The description adds no meaning beyond what the schema already provides for the eight parameters; 'simple parameters' is not parameter semantics.

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

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

The description states a specific verb and resource: 'Create a KPI visual', which clearly identifies the action and the artifact. It distinguishes this tool from sibling visual creators like create_bar_chart or create_line_chart by naming the KPI type, though it does not explicitly contrast them or clarify scope.

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

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

There is no guidance on when to use this tool versus alternatives such as add_visual or other create chart tools. No prerequisites, conditions, or exclusions are mentioned; the phrase 'from simple parameters' provides no actionable selection criteria.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not that this mutates the analysis, not the required permissions, not whether the chart is persisted to the given sheet, and not what happens on invalid column or aggregation values. Only 'from simple parameters' hints that inputs are lightweight, which is not meaningful disclosure.

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 a single front-loaded sentence with no padding, but the brevity comes from under-specification rather than efficient communication — 'from simple parameters' is filler that consumes a clause without conveying information.

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

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

For a 10-parameter, 7-required mutation tool with no annotations, the description is far too thin. It never explains how analysis_id, sheet_id, and dataset_identifier relate, how date_column/value_column map to axes and granularity, or what the returned chart reference looks like — even though an output schema exists, the input contract is left to the schema alone.

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

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

Schema description coverage is 80%, so the schema already documents most parameters (title, sheet_id, analysis_id, date_column, value_column, value_aggregation, dataset_identifier), warranting the baseline 3. However, the description adds no syntax, format, or dependency detail, and leaves format_string and show_data_labels undocumented in both places.

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 verb+resource ('Create a line chart') is unambiguous, but it largely restates the tool name and adds the empty qualifier 'from simple parameters'. It never distinguishes this tool from the many sibling chart creators (create_bar_chart, create_pie_chart, create_combo_chart, create_kpi) or explains when a line chart is the right visual choice.

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

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

There is no when-to-use guidance, no prerequisites (e.g., must the sheet/analysis already exist), and no mention of the sibling chart-creation tools. The agent is left to infer selection entirely from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. 'Create' implies a mutation to the analysis, but the description does not say whether it modifies the analysis definition, what permissions are needed, whether the operation is reversible, or how it interacts with the referenced dataset/sheet. Only the bare mutation semantic is conveyed.

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 short sentence, front-loaded with the verb and resource, which is appropriately sized. The phrase 'from simple parameters' is filler that does not earn its place, keeping it just short of 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?

This is a complex mutation tool with 8 parameters (7 required) that references an analysis, sheet, and dataset, yet the description explains none of that context. An output schema exists so return values need not be described, but the absence of any prerequisite or scoping information leaves the definition incomplete for correct invocation.

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

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

Schema description coverage is 100%, so all eight parameters are already documented in the schema, giving a baseline of 3. The description adds nothing beyond that — 'simple parameters' is vague and does not explain the relationship between group_column, value_column, value_aggregation, or the required analysis_id/sheet_id/dataset_identifier set.

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 pie chart'), so an agent immediately knows the operation. However, it does nothing to distinguish this tool from siblings like create_bar_chart, create_line_chart, or create_combo_chart beyond the chart type name, and the trailing phrase 'from simple parameters' adds no discriminating information.

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

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

There is no guidance on when to choose a pie chart over the sibling chart-creation tools, nor any mention of prerequisites such as the analysis or sheet having to exist first. The description is silent on all usage context.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does not state that this is a mutating operation, what permissions or IDs are required, what happens to the target sheet, or how errors are surfaced; only the word 'Create' implies mutation.

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

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

The definition is a single front-loaded sentence with no unnecessary repetition. However, 'from simple parameters' is vague filler and the brevity comes at the cost of useful detail.

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

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

For a 7-parameter required mutation tool with no annotations, the description is too thin. The output schema means return values need not be explained, but the description omits routing guidance, prerequisites, and behavioral context that an agent would need before invoking 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 description coverage is 100%, so all seven parameters are documented in the schema. The description adds no meaning beyond 'simple parameters' and does not explain relationships such as analysis_id/sheet_id or the row/value/aggregation structure. 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 has a clear verb+resource: 'Create a pivot table.' It does not distinguish the tool from the many sibling creation tools such as create_table, create_kpi, or create_bar_chart, and the phrase 'from simple parameters' adds no specific scope.

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

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

No when-to-use guidance is provided. The description does not mention alternatives, prerequisites, or the circumstances under which a pivot table should be chosen over create_table or a calculated field.

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

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

With no annotations provided, the description carries the full behavioral burden, and it discloses almost nothing. "Create" implies a write, but there is no statement about permissions, whether an existing table is replaced, what happens to the target sheet, or any side effect. Only the implied mutation verb gives it any credit.

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 short sentence that is front-loaded with the action and resource. It loses a point for the trailing "from simple parameters," which is vague filler rather than useful information.

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

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

An output schema exists, so return values need not be explained, and the schema fully documents the parameters. What is missing is behavioral context for a mutating tool with no annotations: placement/ordering of the created table, permission requirements, and overwrite semantics are all 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 all five parameters (title, columns, sheet_id, analysis_id, dataset_identifier) are already documented in the schema, including the comma-separated column format. The description adds no parameter meaning beyond "simple parameters," 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 states a verb and resource ("Create a flat table visual"), and the word "flat" loosely differentiates it from the sibling create_pivot_table. However, it never names an alternative, and "from simple parameters" is filler that adds no specificity about scope or behavior.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to the many sibling visual-creation tools (create_kpi, create_bar_chart, create_pivot_table, add_visual). The agent must infer that this is the right tool for a flat table purely from the name.

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 destructiveHint=true by naming the concrete failure mode (references in visuals and other calculated fields break) and disclosing that a backup is automatically created. These are operationally important facts an agent cannot derive from annotations or 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-loads the one-line purpose, then the destructive warning, then the mitigation tool, then the backup reassurance. Every sentence earns its place with no filler.

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

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

With a destructive annotation, full schema coverage, and an output schema present, the description supplies exactly the missing pieces: blast radius, a verification tool, and backup behavior. Nothing needed for correct invocation is absent.

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 (name, analysis_id) are documented in the schema, so the description adds no parameter-level detail. Baseline 3 applies when structured fields already do the work.

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 (delete) and resource (calculated field) scoped to a QuickSight analysis, distinguishing it cleanly from its siblings add_calculated_field, update_calculated_field, and list_calculated_fields.

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 run get_columns_used first to assess impact, which is actionable prerequisite guidance naming a sibling tool. It stops short of stating when deletion should be avoided altogether versus using update_calculated_field 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 only declare destructiveHint=true, so the description carries meaningful extra weight: it discloses a cascade side effect ('automatically removes filter groups scoped to deleted sheets') and a safety net ('a backup is automatically created'). Those are exactly the behavioral facts an agent needs before invoking a destructive bulk tool and are not derivable from the annotation.

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 lines, front-loaded with the action and scope before context, side effects and warning. The 'WARNING: This is destructive' clause partially restates the destructiveHint annotation, so it is slightly less economical than it could be, though pairing it with the backup note justifies 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?

With an output schema present, return values need no explanation, and the description covers scope, cascade behavior and backup creation. Minor gaps remain: no statement of required permissions, and no note of what happens when the analysis contains no empty sheets.

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 (analysis_id, name_contains) are fully documented in the schema, including the default and case-insensitive behavior. The description's 'all empty sheets' phrasing only implicitly confirms the no-filter default, adding no real semantics 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 and resource ('Delete all empty sheets') and operationalizes the target with '(0 visuals) from an analysis,' which an agent can act on immediately. It is clearly distinct from the single-sheet sibling delete_sheet by its bulk, predicate-based scope.

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

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

Names the triggering situation explicitly ('clean up orphan sheets left by failed operations'), which is strong context. It does not, however, state when NOT to use it (e.g., prefer delete_sheet for a single named sheet) or mention any prerequisites such as permissions on the parent analysis.

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 destructiveHint=true generically. The description adds real behavioral context: what actually breaks (data displayed in affected visuals changes) and that a backup is automatically created before deletion. That is meaningful disclosure beyond the annotation.

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 lines: purpose first, then a bolded WARNING, then the mitigating backup fact. Every sentence earns its place and the destructive nature 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?

An output schema exists so return values need no explanation, and the description covers impact and backup behavior. It stops short of noting permissions or recovery path for the backup, which would complete the picture for a destructive 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% with only two simple string params, so the description correctly does not duplicate them. However, it adds no extra meaning about ID sources or format, 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 (Delete) and resource (filter group) scoped to a QuickSight analysis, which separates it cleanly from sibling add_filter_group and from delete_visual/delete_parameter. An agent knows exactly what object type is being removed.

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

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

Usage is implied by the destructive warning, but the description never states when to delete versus alternatives (e.g., disabling or editing the filter group, or whether backup_analysis should be run first). No explicit when-not guidance is given.

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

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

Annotations only declare destructiveHint=true, while the description adds real behavioral context: cascading breakage of filters/calculated fields/controls, the recommended pre-check, and the important fact that a backup is automatically created before deletion. This is exactly the value the description should add.

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 action, then a clearly delineated WARNING, remediation, and a reassurance about backups. Four short sentences, each carrying distinct information, with zero filler.

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

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

An output schema exists so return values need no explanation. For a destructive two-parameter mutation, the description covers blast radius, prerequisites, and recovery, leaving nothing an agent needs to know before calling 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 description coverage is 100%, so both analysis_id and parameter_name are already documented in the schema. The description adds no syntax or format meaning beyond that, which matches the baseline 3.

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 (Delete) plus resource (parameter) and scope (from a QuickSight analysis). It is clearly distinguishable from the many other delete_* siblings such as delete_calculated_field, delete_visual, and delete_sheet.

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 directs the agent to 'Check get_parameters first to understand dependencies,' naming the concrete alternative prerequisite. It does not state when-not to use the tool, so it falls just short of the top tier.

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?

destructiveHint=true already tells the agent this is a destructive write, but the description adds genuinely new behavioral context: all visuals on the sheet are removed and a backup is automatically created first. That recoverability detail is not derivable from annotations or schema. It stops short of 5 because it says nothing about permissions or whether the backup must be named/retrieved.

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 lines: purpose first, then a clearly flagged WARNING with the consequence and the safety net. Every sentence earns its place and the risk is front-loaded rather than 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?

An output schema exists, so return values need not be explained, and the annotations plus description cover the mutation's risk profile well. The only minor gap is that the description does not mention prerequisites such as required permissions on the analysis.

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

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

Schema description coverage is 100% for both analysis_id and sheet_id, so the schema already carries the parameter burden. The description adds no syntax, format, or lookup guidance beyond that, making the baseline 3 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 ('Delete a sheet from a QuickSight analysis'), which immediately separates it from add_sheet, rename_sheet, and replicate_sheet. It does not, however, explicitly distinguish itself from the nearest sibling, delete_empty_sheets, so it stops short of a 5.

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

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

Usage is implied by the operation name and the destructive warning, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of the alternative bulk sibling delete_empty_sheets. The warning implies 'use deliberately,' which is thin 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 destructiveHint annotation already flags this as a write operation, but the description adds real value beyond it: it discloses that the layout element is removed alongside the visual (a side effect not obvious from the name) and that a backup is automatically created first. It stops short of permissions or reversibility details, so 4 rather than 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?

One sentence of purpose followed by a front-loaded WARNING block. Every sentence carries information an agent needs (destructive, layout element removal, automatic backup), with no filler.

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

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

With annotations covering the safety profile and an output schema covering return values, the description only needs to convey destructive semantics — which it does, including the backup guarantee. It is slightly thin on preconditions (e.g., whether the analysis must be in an editable state), but nothing essential is missing.

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

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

Schema description coverage is 100% and both required parameters are documented in the schema itself. The description adds no syntax, format, or constraint detail beyond what the schema already provides, 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 states a specific verb ('Delete') and resource ('a visual from a QuickSight analysis'), which cleanly separates it from delete_sheet, delete_empty_sheets, and delete_calculated_field. 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?

Usage is implied by the delete verb and the analysis_id/visual_id scope, but there is no explicit when-to-use, when-not-to-use, or prerequisite guidance. Since no sibling tool performs visual deletion, the lack of alternatives is tolerable, keeping this at minimum-viable rather than poor.

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, so the safety profile is covered. The description adds useful scope information by clarifying that the output is an overview rather than the full raw definition, but it says nothing about size limits, latency, or auth requirements. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Two sentences, front-loaded with the core action and followed by a scoping clarification. No filler, though the em-dash clause could be tightened. Efficient overall.

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

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

For a single-parameter read tool with annotations and an output schema, the definition covers what the tool does and why to use it. Nothing essential is missing, though a note on output format or comparison to closely-related siblings would improve it further.

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

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

There is a single parameter (analysis_id) with 100% schema description coverage, so the schema already documents it fully. The description contributes no additional parameter meaning, making the baseline 3 correct.

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

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

States a specific verb and resource ('Get a structured summary of a QuickSight analysis') and explicitly distinguishes itself from the raw variant by noting it returns an overview 'without the full raw definition.' An agent can separate it from get_analysis_raw 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?

Provides clear context: 'ideal for understanding what an analysis contains before making changes.' This tells the agent when the tool is appropriate, though it doesn't state explicit exclusions or name alternatives beyond the implicit contrast with the raw definition.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's job is to add context — and it does, framing the tool as a QA check that surfaces added/removed/modified deltas and states the ordering prerequisite (must follow snapshot_analysis and a change). It does not describe output format or failure modes, but the output schema covers returns.

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 paragraphs, front-loaded with the core action and followed by the when-to-use condition. The "QA reviewer" line is mildly flourishy but reinforces intent rather than wasting 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 annotations covering the safety profile and an output schema explaining the delta result, the description needs only to say what is compared and when. It covers both, though it could note what the diff does when no changes occurred.

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

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

Schema description coverage is 100%, so both parameters (analysis_id, snapshot_id) are already documented, including that snapshot_id comes from a prior snapshot_analysis call. The description adds no syntax, format, or matching semantics 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?

States a specific verb (compare) and resource (current analysis state vs a previous snapshot), and implicitly distinguishes itself from snapshot_analysis by referencing the snapshot it consumes. An agent can tell what this tool returns 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?

"Use AFTER making changes to see what was added, removed, or modified" gives a clear temporal trigger and intent. It does not name an explicit alternative or a when-not-to-use case, so it falls just short of 5.

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

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

With readOnlyHint already declaring the safety profile, the description still adds real behavioral value: it returns the Definition dict verbatim as stored by AWS, and it warns that output can be very large for complex analyses. It omits any mention of auth/permission requirements or whether the raw structure is safe to feed back into update tools despite suggesting that use case.

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 rationale, then the size warning at the end — a sensible ordering. The 'Return the full Definition dict exactly as stored by AWS' sentence is slightly redundant with the opening line but earns its place by specifying verbatim output.

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, single-parameter tool with an output schema present, the description covers purpose, intended use, and the key operational risk (large output). What remains missing is any pointer on how to obtain a valid analysis_id or which sibling to prefer for a lighter-weight view.

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

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

Schema coverage is 100% and the single analysis_id parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no format, source, or ID-discovery guidance beyond what the schema already provides.

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

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

States a specific verb and resource ('Get the complete raw analysis definition') and qualifies it with 'raw' and 'exactly as stored by AWS', which separates it somewhat from describe_analysis and snapshot_analysis. However, it never names a sibling tool or contrast case, so an agent still has to infer when raw retrieval beats a summarized describe call.

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

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

Provides concrete use contexts — debugging, manual inspection, and extracting complex structures to pass to other tools — which is meaningfully more than implied usage. It stops short of stating when NOT to use it (e.g., use describe_analysis for a cheap overview), so no exclusions or named alternatives are given.

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

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

The readOnlyHint annotation already declares this is a safe read operation, so the description's burden is lower. However, the description does not add any behavioral context such as error handling for missing fields or 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?

A single, efficient sentence with the core action and resource front-loaded. No unnecessary 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?

With an output schema present, the description needn't explain return values, but it still lacks usage guidance and any behavioral caveats. For a simple retrieval tool with full schema coverage and annotations, it is adequate but leaves clear gaps in routing.

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 both parameters are fully documented in the schema. The description adds no additional meaning beyond what the schema provides, which is the baseline expectation.

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 (Get details) and resource (calculated field in an analysis), clearly distinguishing it from siblings like list_calculated_fields, add_calculated_field, and update_calculated_field.

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?

No guidance is given on when to use this tool versus alternatives like get_analysis_raw or list_calculated_fields. The agent is left to infer that this is for retrieving one specific field by name rather than listing all fields.

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?

readOnlyHint=true already tells the agent this is a safe read, and an output schema exists so return values need no explanation. The description does add the notion that the result is a frequency map (counts, not a plain list), which is useful behavioral context, but says nothing about auth needs, scope limits, or cost.

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?

One tight sentence with no filler and the key concept front-loaded. It is efficient rather than padded, though it is arguably too terse for a tool sitting among many column/field-related siblings.

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?

Low-complexity read-only tool with one required parameter and an output schema, so most structure is already covered. What is missing is any routing context among the ~60 siblings or note on scope (single analysis vs. all visuals), which leaves a gap for correct selection.

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 single documented analysis_id parameter, so the schema carries the burden. The description adds no extra meaning about the parameter, making the baseline 3 correct.

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

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

The description names a specific verb ('Get') and a specific resource with scope ('frequency map of columns used across an analysis'), so an agent can tell it apart from list_calculated_fields or get_parameters. It stops short of explicitly naming which sibling it competes with, which keeps it out of the top band.

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

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

There is no statement of when to use this tool, when not to, or which alternative (e.g. list_calculated_fields, get_visual_definition) covers a related question. Usage is only implied by the phrase 'columns used'.

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 annotation already establishes that this is a safe read operation. The description adds no behavioral context beyond that, such as result ordering, pagination behavior, or whether the current version is included in the list. For a history-listing tool, those traits matter to an agent's invocation.

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, efficient sentence with the core purpose front-loaded. Every word earns its place and nothing 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 the low complexity, complete parameter documentation, and an output schema that covers return values, the description is nearly sufficient. The only minor gap is that it does not mention result ordering or pagination behavior, which the limit parameter and output schema likely handle.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description adds no additional meaning about parameter usage, which is the correct baseline 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 names a specific verb ('List') and resource ('version history of a QuickSight dashboard'), making the tool's purpose immediately clear. It does not explicitly differentiate itself from sibling tools like rollback_dashboard or publish_dashboard, but the scope is unambiguous for an agent scanning the tool list.

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

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

The description gives no guidance on when to use this tool versus alternatives such as rollback_dashboard or list_dashboards. It implies the obvious use case of inspecting version history, but provides no explicit context, prerequisites, or exclusions.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description's burden is lower. It adds that the result is 'full metadata', which usefully signals completeness versus a summary view, but says nothing about permissions, missing-dataset behavior, or size.

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?

One sentence, front-loaded verb and resource, zero filler. Nothing to trim.

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

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

For a simple single-parameter getter with an output schema present, the description covers what is needed; return values need not be described. It is slightly thin on error or permission behavior but is adequate overall.

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?

Single required parameter with 100% schema description coverage, so the schema fully documents 'dataset_id'. The description adds no format, lookup, or resolution detail beyond the schema — the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('metadata for a QuickSight dataset') with the scope qualifier 'full'. This clearly separates it from list_datasets, search_datasets, and the SQL-specific siblings, but it never explicitly names what distinguishes it from, e.g., get_dataset_sql.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives. An agent must infer from the name alone that this retrieves dataset metadata rather than SQL or refresh state.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds only that the payload is the SQL query behind the dataset, which is mildly useful context but discloses nothing about permissions, rate limits, or the fact that only custom-SQL datasets actually have a query.

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?

One sentence, front-loaded with the verb and resource, with zero filler. Nothing could be removed without losing meaning.

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 an output schema present and annotations covering the safety profile, the description need not explain return values, and for a one-parameter getter it is nearly sufficient. The one gap is that it doesn't warn that datasets without custom SQL have no query to return, which would prevent a confused call.

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 there is a single required parameter, so the schema fully documents dataset_id. The description adds no syntax, format, or sourcing detail beyond what the schema already provides, 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 ('Get') and resource ('SQL query powering a QuickSight dataset'), which is unambiguous and clearly distinct from write siblings like update_dataset_sql or modify_dataset_sql. It does not, however, explicitly name those siblings or call out that this is the read counterpart, so it stops short of a 5.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent must infer from the name alone that this is the read-only way to inspect a dataset's SQL and that update_dataset_sql/modify_dataset_sql are the mutation paths.

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 annotation already tells the agent this is a safe read operation. The description adds that it 'analyzes your error history' and what categories it covers, but discloses nothing about data sources, time windows, rate limits, or how much history is scanned, so it only modestly exceeds the annotation baseline.

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

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

The purpose is front-loaded and the body is well organized into a short prose block plus a 'Returns' list. The Returns section partly duplicates what the output schema already declares, which is a minor redundancy but not wasteful enough to hurt readability.

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 diagnostic tool with annotations and an existing output schema, the description covers purpose, trigger conditions, and the categories of error it addresses. An agent has everything needed to decide to call it and interpret the result.

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

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

The tool takes zero parameters, so per the rubric this is a baseline 4. There are no inputs whose semantics need explaining, and the description correctly does not invent any.

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 ('Show common QuickSight errors and their known fixes') and adds domain specificity by naming SPICE refresh, permission, and throttling failures. It is clearly about error-pattern analysis, though it does not explicitly differentiate itself from adjacent diagnostic siblings like verify_analysis_health or get_learning_insights.

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

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

The final sentence gives an unambiguous trigger: 'Call this when something goes wrong to see if it is a known issue with a known fix.' It states clear usage context but offers no explicit exclusions or named alternative tools for diagnosis, keeping it short of a 5.

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

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

The readOnlyHint=true annotation already establishes this is a safe, non-mutating read, so the description need not repeat that. However, it adds no behavioral context of its own — no note on pagination, ordering, or whether the list is complete for nested/linked analyses. A minimal but acceptable contribution given 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?

One front-loaded sentence with the verb and scope stated immediately and no filler. It is efficient, though slightly under-powered for a tool with an output schema whose contents go unmentioned.

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

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

For a one-parameter read tool with full schema coverage and an existing output schema, the description supplies what the agent needs to invoke it correctly. The only mild gap is not noting how the returned filter groups relate to the add/delete filter group siblings.

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

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

There is a single required parameter and schema description coverage is 100%, with the schema already stating 'The QuickSight analysis ID.' The description adds no format, sourcing, or lookup guidance beyond that, 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 ('List') and resource ('filter groups') scoped to a QuickSight analysis, which is enough to distinguish it from add_filter_group and delete_filter_group. It is clear but does not explicitly name what it is not, and 'filters' vs 'filter groups' could be briefly ambiguous.

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?

No indication of when to use this rather than sibling read tools such as get_parameters or describe_analysis, and no prerequisites or exclusions. The agent must infer usage entirely from the name.

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 readOnlyHint=true, so safety is already known. The description adds important behavioral context: it discloses what the server tracks (tool calls, failures, latency), what the return fields are (most_used_tools, slowest_tools, error_rate, recommendations), and notes that insights improve with more usage. This goes beyond annotations and schemas. However, it doesn't detail performance characteristics, data retention, or whether insights are per-user or global.

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 purpose, then lists return fields in a structured way. It is concise and avoids fluff, though the 'Returns:' section could be considered slightly verbose given an output schema exists. Overall, 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?

Given that an output schema exists, the description needn't detail return values, but it does provide a helpful summary of them. The description covers what insights are surfaced and how they improve with usage. It might benefit from mentioning whether insights are user-specific or server-wide, but for a read-only analytics tool, it is sufficiently complete.

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

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

Parameter count is 0 and schema description coverage is 100%, so baseline is 4. The description correctly implies no inputs are needed. No parameter semantics are relevant here, so the baseline score of 4 is appropriate.

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

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

The description states a specific verb and resource: 'Show what the server has learned from your QuickSight usage patterns.' It immediately distinguishes itself from all sibling tools by focusing on server-side usage analytics/telemetry rather than QuickSight asset manipulation. No sibling tool is about learning insights from usage patterns.

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

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

The description implies the tool is useful for understanding usage patterns and mentions recommendations, but it does not explicitly state when to call it versus alternatives or provide exclusion criteria. The purpose is self-evident enough that a user can infer usage, but there's no guidance like 'call this before optimizing workflows' or 'not for real-time monitoring'.

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 annotation already tells the agent this is a safe read. The description adds only that it lists 'all' parameters scoped to a specific analysis, which is mild scoping context. It does not mention pagination, return format, or any other behavioral detail beyond what the annotation provides.

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

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

The description is a single front-loaded sentence with no wasted words. It states the action and scope immediately.

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

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

For a simple read-only tool with one parameter, an output schema, and a readOnlyHint annotation, the description is nearly complete. It could add a brief note on when to prefer it over get_filters or list_calculated_fields, but return values are covered by the 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 description coverage is 100%, so the sole parameter (analysis_id) is already fully documented in the schema. The description only implies that the parameter identifies the analysis; it adds no syntax, format, or additional meaning beyond the schema.

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

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

The description states a specific verb and resource: 'List all parameters' and scopes them to a 'QuickSight analysis.' This clearly distinguishes it from mutation siblings like add_parameter and delete_parameter, though it does not explicitly name 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?

The description implies usage (call this when you need to see parameters in an analysis) but provides no explicit when-to-use guidance, exclusions, or named alternatives among the many sibling tools. The implied context is adequate for a simple read-only list.

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, matching the 'check' wording, so no contradiction. But the description adds nothing beyond that: no note on whether statuses are terminal/pending, whether polling is expected, or how long results remain queryable.

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

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

A single front-loaded sentence with zero waste. It is concise and well-structured, though the brevity leaves gaps rather than being tightly complete.

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

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

An output schema exists, so return-value explanation is unnecessary. However, for a status-polling tool in a family containing refresh_dataset/cancel_refresh/list_recent_refreshes, the absence of any workflow or usage context leaves it only minimally complete.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the pointer back to refresh_dataset. The description contributes no additional parameter 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?

States a specific verb (check) and resource (SPICE dataset refresh status), and the schema ties it to dataset_id/ingestion_id from refresh_dataset. It doesn't explicitly distinguish itself from list_recent_refreshes or cancel_refresh, which are the nearest siblings, so it falls short of a 5.

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

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

No guidance on when to use this versus list_recent_refreshes, refresh_dataset, or cancel_refresh. The only contextual link, that ingestion_id comes from refresh_dataset, lives in the schema, not the description. An agent must infer the polling/status-check workflow itself.

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, so the description needn't re-establish safety. It adds real value beyond that by disclosing the shape of the returned definition (field mappings, aggregations, formatting, chart configuration) and its reuse in add_visual. Auth requirements and failure modes are still unmentioned.

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, followed by what the definition contains and the copy workflow. No sentence is 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 an output schema present, return values need not be described, and the description still adds useful summary of the definition's contents plus the add_visual reuse pattern. Nothing needed to call this tool correctly is missing.

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

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

Both parameters are documented in the schema at 100% coverage, including what visual_id and analysis_id mean, so the description carries little additional burden. It adds no format, prefix, or lookup guidance beyond the schema, making the 3 baseline correct.

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

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

The description states a specific verb and resource ('Get the full raw definition of a specific visual') and names the scope ('full raw definition'), which cleanly separates it from list_visuals (enumeration) and get_analysis_raw (different resource). An agent can identify the tool 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 clear use case ('inspect a visual's complete configuration') and a downstream workflow: the result can be modified and passed to add_visual to create a copy. This implicitly routes the agent away from list_visuals and toward the copy workflow, but no explicit when-not condition is 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, so the safety profile is covered. The description adds meaningful extra context: results are cached for 5 minutes, every analysis in the account is returned, and status values are enumerated (CREATION_SUCCESSFUL, UPDATE_SUCCESSFUL, etc.), which helps the agent interpret 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?

Front-loaded with the core action, then scope, caching, and field list. Well structured with a bullet list, though the per-field enumeration partially overlaps with the existing output schema and could be trimmed.

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

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

An output schema exists, so return-value documentation is not strictly needed, yet the description still covers scope, caching, and status values. It is complete for a no-parameter list tool; only the missing sibling routing keeps it from a 5.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly describes no inputs and instead documents the returned fields, which is more than required.

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 all QuickSight analyses') plus the fields returned. It does not explicitly differentiate itself from the sibling search_analyses, so an agent must infer that this returns the full unfiltered set.

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 this to discover analyses before inspecting them' gives implied workflow context, and 'Returns every analysis in the account' hints at the unfiltered scope. However, it never names search_analyses or describe_analysis as alternatives or states when this is the wrong choice.

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, so the safety profile is covered. The description adds the scoping context (all fields within a given analysis), but discloses nothing about result ordering, size, or pagination behavior.

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

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

A single, front-loaded sentence with zero waste; every word earns its place and the resource and scope lead the statement.

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

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

An output schema exists, so return values need not be described, and the single parameter is documented in the schema. For a simple list tool with annotations, this is nearly complete, with only usage routing left unstated.

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 analysis_id is fully documented in the schema. The description adds no syntax or format detail beyond what the schema already provides, making the baseline 3 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 gives a specific verb ('List') and resource ('calculated fields') scoped to a QuickSight analysis. It is clearly a read/collection operation, distinguishable from the singular get_calculated_field, though it does not explicitly name or contrast with that sibling.

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

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

There is no when-to-use guidance, no alternatives named, and no exclusions. The agent must infer that this returns the full set while get_calculated_field fetches one by name.

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

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

With readOnlyHint already declared, the description adds genuinely new behavioral context: a 5-minute result cache, account-wide scope, and the domain note that dashboards are the published, viewer-facing version of analyses. It stops short of describing pagination or result-size limits for a potentially large account-wide 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?

Front-loaded with the verb and resource, followed by scope and caching, then a compact field breakdown. Generally tight, though the bulleted field list overlaps with the output schema and adds a little redundancy.

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

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

For a zero-parameter read tool with annotations and an output schema, the description covers scope, caching, domain meaning, and return fields. Nothing essential is missing; only pagination/volume expectations 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?

The tool takes no parameters, so the baseline is 4. The description instead documents the shape of each returned entry, which is extra detail beyond the zero-parameter schema, though it partially duplicates the existing output 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 all QuickSight dashboards') and enumerates the fields returned (names, IDs, publish status). The 'Returns every dashboard in the account' clause implicitly separates it from search_dashboards, but it never names that sibling explicitly, so differentiation is inferential rather than stated.

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

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

The claim that it returns every dashboard implies a full-enumeration use case, and the field list hints at when the output is useful. However, there is no explicit when-to-use guidance, no exclusion ('do not use when you need a filtered subset — use search_dashboards'), and no prerequisites stated, despite search_dashboards sitting right there in the sibling list.

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 annotation, the description discloses a 5-minute result cache, which materially affects how an agent should treat freshness. It also explains the import_mode values (SPICE cached vs DIRECT_QUERY live), adding real semantic context. Minor gap: no disclosure of pagination or result-size limits for a whole-account 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?

Front-loaded with the action and resource, then a compact bulleted field list, then usage and caching notes. The field enumeration is slightly redundant given an output schema exists, but it is short and readable.

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

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

With an output schema present, the description didn't need to restate return fields, yet it still explains import_mode semantics and caching, which the schema cannot convey. It is essentially complete for a no-argument discovery tool, missing only guidance on volume/pagination.

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 of 4 applies. There are no parameter semantics to document and the description appropriately spends no space on them.

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

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

The opening sentence states a specific verb and resource ('List all QuickSight datasets') and enumerates the returned fields. It does not, however, differentiate itself from the closely related sibling search_datasets (the filtered variant), leaving an agent to infer which listing tool to pick.

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

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

It gives clear downstream context: 'Use this to discover datasets before calling get_dataset_sql or update_dataset_sql,' which tells the agent where this fits in a workflow. It stops short of stating when NOT to use it or naming search_datasets as the filtered alternative.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only that it's SPICE refresh history scoped to a dataset, but doesn't disclose ordering, pagination, or what fields a refresh record contains, leaving behavioral gaps despite the light 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?

A single, front-loaded sentence with no wasted words. Appropriate size for a simple list tool.

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

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

With an output schema present and annotations covering read-only safety, the description needs only to state purpose and scope, which it does. Minor gaps remain around sibling differentiation and return ordering, but overall it's sufficient for correct invocation.

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

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

Schema description coverage is 100% with both parameters fully documented in the schema (limit default and dataset_id). The description adds no parameter syntax or format 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?

States a specific verb 'List' and resource 'SPICE refresh history for a dataset', which is clear. However, it doesn't distinguish itself from closely related siblings like get_refresh_status or refresh_dataset, leaving ambiguity about when this read-only history listing is preferred over those.

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?

No guidance on when to use this tool versus get_refresh_status, refresh_dataset, or cancel_refresh. An agent must infer that this is for historical listing only, with no explicit conditions or alternatives offered.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds no further behavioral context — no pagination behavior, no note on what happens with an empty sheet or an invalid sheet_id, and no indication of result volume. An output schema exists, which covers returns, but the description itself contributes nothing beyond the safety profile already 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?

A single sentence that front-loads the action and resource, with no filler or redundancy. Nothing 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?

With an output schema covering return values, full parameter documentation, and a readOnly annotation, the description needs only to convey scope and purpose — which it does. It falls short only in not distinguishing itself from the closely named sibling list_visuals.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline of 3 applies. The description does not clarify the relationship between analysis_id and sheet_id or how to obtain a sheet_id (e.g., via add_sheet or a sheet-listing call), adding no meaning beyond the schema.

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

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

States a specific verb ('List'), resource ('visuals'), and scope ('in a specific sheet of a QuickSight analysis') — the sheet-level scoping separates it from the analysis-wide sibling list_visuals. It does not name that sibling explicitly, so the differentiation is implied rather than stated.

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

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

The scope ('a specific sheet') implies when the tool applies, but there is no explicit when-to-use guidance, no mention of the alternative list_visuals, and no prerequisites or ordering hints. Usage is inferable but not taught.

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=true annotation already declares this as a safe, non-mutating read. The description adds that results carry 'type and location info', a mild bit of behavioral context, but this overlaps with the output schema and no pagination, scoping, or auth behavior is disclosed.

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

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

A single front-loaded sentence with no filler; the verb and resource lead. It is efficient, though it could carry slightly more routing detail at the same length.

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 listing tool with an output schema and full schema description coverage, the definition is adequate: the agent knows what it returns and what to pass. The only real gap is the unstated relationship to 'list_sheet_visuals'.

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 a single documented 'analysis_id' parameter, so the schema fully carries parameter meaning. The description adds nothing beyond the schema, which is the baseline expectation at this coverage level.

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 ('List') and resource ('visuals in a QuickSight analysis'), plus the returned fields ('type and location info'). It scopes the tool to the analysis level, but does not explicitly distinguish it from the closely related sibling 'list_sheet_visuals', leaving that contrast 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as 'list_sheet_visuals' or 'get_visual_definition'. Usage must be inferred from the name and the phrase 'in a QuickSight analysis'.

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 destructiveHint=true, so the description adds real value: it discloses the read-modify-update mechanism and, crucially, that a backup is created automatically, which materially softens the destructive risk. It stops short of stating permissions or how the replacement handles multiple matches.

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, then mechanism, then the backup caveat. Slight redundancy between the first two sentences ('find and replace text' vs 'applies a string replacement'), but no wasted padding.

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

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

With an output schema present, a single destructive annotation, and full param coverage, the description supplies the missing behavioral context (auto-backup) and is sufficient for correct invocation. Only the sibling-routing detail is absent.

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 find, replace, and dataset_id are already fully documented. The description confirms the replacement semantics ('applies a string replacement') but adds no format, matching, or case-sensitivity detail beyond the schema, so the baseline 3 holds.

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

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

States a specific verb+resource pair (find and replace text in a dataset's SQL query) and clarifies it is a convenience wrapper over read-modify-update. It does not, however, explicitly distinguish itself from the sibling update_dataset_sql or get_dataset_sql, leaving the agent to 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?

Calling it a 'convenience tool' implies it is for narrow string substitutions rather than full SQL rewrites, which is useful implied guidance. But there is no explicit when-to-use/when-not statement naming update_dataset_sql as the alternative for larger edits.

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 destructiveHint=true, but the description goes well beyond that: it specifies that ALL existing dashboard content is replaced and that viewers see the new version immediately. This is exactly the impact-level detail an agent needs before invoking a destructive tool, and it is consistent with the annotation.

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, the warning follows, and the numbered best-practice list is scannable and actionable. The four-step list is slightly verbose for a 3-parameter tool, but every line 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?

With an output schema present, the description need not explain return values, and it covers what remains: the destructive semantics, the audience impact, the recovery path, and the recommended pre-flight steps. Nothing essential to invoking this tool safely is missing.

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

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

Schema description coverage is 100%, so dashboard_id and source_analysis_id are already fully documented. The description adds only a weak hint ('publish with a descriptive version_description'), which is largely redundant with the schema's own example. 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 (publish) and resource pair (analysis → existing dashboard), naming both source and target. An agent can immediately distinguish it from siblings like clone_analysis, backup_analysis, or get_dashboard_versions without opening a schema.

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

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

Explicitly provides a when-to-use workflow and names the alternatives at each step: clone_analysis to test, backup_analysis to back up, rollback_dashboard to recover. It even flags the prerequisite that the analysis must be tested thoroughly first, 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?

With no annotations, the description carries the full behavioral burden. It discloses the operation is a trigger and that it is a no-op on DIRECT_QUERY datasets, but omits whether the refresh is asynchronous, what happens on failure, permission requirements, or rate limits. For an action-triggering tool with zero annotation coverage this is adequate but leaves meaningful 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?

Three short sentences, all load-bearing: what it does, when to use it, and its exclusion case. The key action is front-loaded with no filler.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description covers the core action and its main caveat. It could still note that refreshes are typically asynchronous and pair with get_refresh_status/cancel_refresh, which keeps it just short of fully complete for a state-changing 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?

There is a single parameter (dataset_id) with 100% schema description coverage, so the schema already documents it fully. The description adds no format, ID-source, or constraint detail beyond the schema, making the baseline 3 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 (trigger) and resource (SPICE refresh / data reload) scoped to a dataset, and adds a clear boundary ('no effect on DIRECT_QUERY datasets') that separates it from read-only dataset tools. An agent can distinguish it from get_refresh_status, list_recent_refreshes, and update_dataset_sql without opening schemas.

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 when-to-use condition ('after updating dataset SQL to reload data into SPICE cache') and an implicit when-not ('no effect on DIRECT_QUERY datasets'). It never names explicit alternatives such as cancel_refresh or get_refresh_status, so it stops short of full alternative routing.

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

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

Annotations only provide idempotentHint=true. The description adds important behavioral context beyond annotations: it modifies the analysis definition and automatically creates a backup before making changes. It still omits permissions requirements, backup/restore details, and output behavior.

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

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

Two short sentences with purpose front-loaded, followed by a critical warning. Every sentence earns its place and no filler is present.

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

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

An output schema exists, so return values need not be explained in the description. The description covers mutation risk and automatic backup, and the schema covers required parameters. It omits minor prerequisites like analysis state or backup retrieval, but is adequate for a simple rename 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 the schema fully documents analysis_id, sheet_id, and new_name. The description adds no additional parameter meaning such as naming constraints or format expectations, 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 ('Rename') and resource ('an existing sheet in a QuickSight analysis'), scoping the operation precisely. It is inherently distinguishable from sibling sheet operations such as add_sheet, delete_sheet, and replicate_sheet, even though it does not name them 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?

The description implies usage when an existing sheet needs renaming, but provides no explicit when/when-not guidance or alternative tool comparisons. The context is clear enough to infer the tool's role among siblings.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses that this mutates the analysis definition, that a backup is created automatically beforehand, and that visual IDs are auto-prefixed with 'rc_'. Gaps remain on permissions/authorization and what happens if the target sheet name already exists, keeping it from a 5.

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

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

Front-loaded with the core action, then usage rationale, then side effects, then a clearly marked WARNING. Every sentence adds distinct information with no 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?

For a mutation tool with no annotations, the description covers the safety-relevant essentials (mutation, automatic backup, ID prefixing) and an output schema exists so return values needn't be explained. Minor omissions like target-name conflict behavior are the only 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 all three parameters (including the pointer to describe_analysis for sheet IDs). The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (copy/replicate) and resource (all visuals from one sheet to a new sheet in the same analysis), and the scope 'same analysis' distinguishes it from clone_analysis. An agent can tell it apart from add_sheet and add_visual 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 positions itself as 'the recommended way to duplicate a sheet' and names the alternative workflow ('adding visuals one at a time') that it beats on reliability. It lacks an explicit when-not-to-use condition, so it falls just short of a 5.

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