oviond

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

The description discloses important non-obvious behavior beyond what annotations provide: each widget is cloned with a fresh ID, widgets are stacked below existing content, and widgets with unavailable datasource/goal/calculated metric connections degrade to demo data instead of erroring. This is exactly the kind of behavioral detail an agent needs before invoking the tool.

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

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

The description is two sentences with no filler: it front-loads the core operation, then details the two most consequential behaviors (fresh IDs/stacking and demo-data fallback). Every sentence and clause earns its place.

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

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

For a create-like operation with four required parameters, full schema coverage, and an output schema, the description is complete. It covers the non-obvious runtime behavior, and the return value is handled by the output schema, so nothing essential is missing.

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

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

Schema coverage is 100%, and each parameter already has a clear description with a source method to obtain it (e.g., 'from list_pages', 'from list_assets'). The tool description adds no extra parameter-level semantics, but the schema fully carries that burden, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the action ('Instantiate an asset's widgets'), the resource ('onto a report page'), and the key side effects that characterize this specific operation: cloning widgets with fresh IDs and stacking them below existing widgets. It is distinguishable from the many single-widget add_* tools because it operates on an entire saved asset/section.

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 tool's use case is clear from the title and first sentence: adding a saved asset's widgets to a report page. It does not explicitly name individual add_*_widget tools as alternatives or state when to prefer this over adding widgets one by one, so it stops just short of full 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?

Annotations already indicate this is a write operation that is not destructive. The description adds a useful behavioral detail: position, width, and height are automatically defaulted. It does not disclose return values or side effects, but the output schema and annotations ease that burden.

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

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

The description is a single, well-structured sentence that front-loads the action and object, then adds one relevant default-behavior note. There is no filler or repetition of schema content.

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

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

For a simple create operation, the description is minimally adequate: the action is clear and all parameters are documented in the schema. However, it does not help an agent distinguish when to choose this widget type over sibling add_*_widget tools, and it does not clarify what the created button widget looks like or how it is returned.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description with source hints like 'from list_pages' and 'from list_reports'. The tool description adds no additional parameter-level meaning beyond noting that layout properties not present in the schema use defaults.

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

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

The description clearly states the action ('Add') and the resource ('a button widget to a page'). It does not explicitly differentiate from the many sibling add_*_widget tools, but the widget type is named directly and the scope is clear.

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_text_widget, add_image_widget, or update_button_widget. The note about defaults is mild usage information, but it does not help an agent choose among the closely related add_*_widget 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?

Beyond the annotations, the description discloses important behavioral traits: the widget displays demo data until attached to a formula, the returned widget_id is required for follow-up updates, and position/width/height match the editor's Calculated Metric card. This gives the agent an accurate model of what happens when the tool is invoked.

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

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

The description is three concise sentences, each earning its place: the first defines the tool and behavior, the second explains the return value and next step, and the third clarifies layout semantics. It is front-loaded with the core action and contains no filler.

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

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

For a create-widget operation with annotations, a 100%-covered schema, and an output schema present, the description covers the essential flow: what is created, what the widget shows, what the return value is, and how to proceed. Nothing critical is missing for an agent to invoke and continue the workflow correctly.

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

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

The input schema already provides 100% parameter coverage with source values from list_reports, list_pages, and list_clients. The description adds workflow context but does not introduce additional parameter meaning beyond what the schema documents, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb and resource ('Add a Calculated Metric widget to a page') and characterizes the widget as a date-trended table showing demo data until linked to a formula. This clearly distinguishes it from the many sibling widget-creation tools, especially add_data_widget and add_custom_data_widget.

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

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

The description gives a clear usage context: create the widget first, then point it at a formula using update_calculated_metric_widget, pulling the formula id from list_calculated_metrics. It does not explicitly state when not to use this tool or name alternatives among sibling widget creators, but the workflow is concrete and actionable.

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

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

Beyond the annotations, the description discloses important behavior: the widget initially shows demo data until pointed at an uploaded CSV dataset, and the returned widget_id is used for later updates. It also specifies that position, width, and height match the editor's Custom Data card. This meaningfully adds behavioral context beyond the readOnlyHint/destructiveHint flags.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then gives the return value and follow-up workflow, and finally the layout behavior. Every sentence contributes useful information.

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

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

The description is complete for a tool with three well-documented parameters and an output schema. It specifies the return value, the relationship to update_custom_data_widget, and the source of IDs and column names. No critical information needed to understand or call the tool is missing.

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

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

The input schema already covers all three parameters at 100% with clear descriptions, so the description does not need to repeat them. It adds contextual workflow information about the widget_id and update path, but not new meaning for the individual parameters. Per the calibration baseline, schema coverage of 100% yields a 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?

The description uses a specific verb and resource: 'Add a Custom Data widget to a page.' It clearly identifies the widget type, which distinguishes it from sibling tools like add_data_widget, add_button_widget, and add_text_widget. It also adds the purpose of the widget (showing demo data until connected to a CSV dataset), making the tool's role unambiguous.

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

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

The description gives clear context for when to use this tool: to add a new Custom Data widget, then later connect it to a dataset via update_custom_data_widget. It mentions related tools (list_custom_data, get_custom_data) that support the follow-up workflow. It does not explicitly state exclusions or compare against sibling add_*_widget tools, but the context is sufficient for an agent to select it.

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

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

Annotations only cover the safety profile (readOnlyHint false, destructiveHint false, openWorldHint false). The description adds genuinely useful behavior beyond that: the call returns a widget_id, the series is fetched asynchronously so get_widget_data must be called to read numbers, and position/size default. It does not mention auth or failure 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?

Front-loads the action, then the configuration rules, then the follow-up call, then the no-config shortcut. Every sentence carries information; the only slightly soft phrase is 'applying the same rules as the report builder', which leans on external knowledge.

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 17-parameter creation tool with an output schema, this covers the essential agent-facing facts: how to discover ids, what gets defaulted, what is returned, and the asynchronous fetch follow-up. It stops short of describing validation failure modes or page-level constraints, which are the only notable gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema can't express: defaults are inherited from the datasource, names/sort/row limit are generated, and the metric/dimension/advanced combination is validated together. That is real added meaning on top of the per-field docs.

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

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

States a specific verb and resource ('Add a DATA widget to a page and configure it'), immediately distinguishing it from the many sibling widget creators (add_text_widget, add_button_widget, add_calculated_metric_widget). The scope of configuration is spelled out as mirroring the report builder.

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 discovery chain ('Discover ids with datasources → describe_datasource') and a distinct use case for a bare call ('Omit the config to drop in a default widget with demo data'). It does not explicitly rule out the sibling widget tools for internal sources like GOALS or CUSTOM_DATA, so routing there is left to inference.

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

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

Annotations already signal a non-read, non-destructive operation, and the description adds meaningful behavioral context: the backend performs DNS provider detection and returns configuration instructions. This helps the agent anticipate the tool's flow without contradicting the annotations.

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

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

Two concise sentences deliver the core purpose and a key behavioral detail without any filler. The most important information is front-loaded in the first sentence.

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

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

For a single-parameter tool with a rich output schema and annotations, this description is complete. It explains what the tool does, what happens during execution, and what the user will need to do afterward, leaving no critical gap for 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?

There is only one parameter and the schema already documents it fully (type, required, description, example). The description does not add further parameter-level detail, but no additional explanation is strictly needed given 100% schema coverage.

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

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

The description uses a specific verb and resource: 'Add a custom domain.' It clearly states the domain is custom and explains the core outcome (backend detects DNS provider and returns needed DNS records), which differentiates it from sibling tools like list_domains and remove_domain.

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

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

The intended use is implied through the phrase 'Add a custom domain,' and the mention of DNS records gives useful context. However, it does not explicitly state when to choose this tool over alternatives, nor does it mention prerequisites or limitations.

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 all default-false (readOnlyHint=false, openWorldHint=false, destructiveHint=false), so they convey no meaningful behavioral profile. The description adds one useful behavioral hint — 'Position, width, and height use sensible defaults' — implying the tool auto-handles layout settings. However, it does not disclose what happens on success, error conditions, or the embed_type/link_url dependency.

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 core action front-loaded and the default-behavior note deferred to the second sentence. There is no filler or redundancy; every word earns its place.

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

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

The description covers the essential purpose and the auto-default behavior, and the presence of an output schema covers return values. However, it leaves the embed_type/link_url relationship implicit and offers no guidance on distinguishing embed widgets from the many sibling widget-add tools, which is a meaningful gap given the large sibling set.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds nothing beyond the schema, which already documents all five parameters, including the embed_type enum and the conditional note on link_url for URL/IFRAME modes. The description does not compensate for any schema gap, but none exists.

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 the verb 'add,' the resource 'embed widget,' and the target 'a page,' clearly identifying the core operation. It distinguishes itself from sibling add_button_widget/add_image_widget/add_text_widget tools by widget type, though the differentiation relies mostly on the name 'embed' rather than a stated contrast.

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

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

No when-to-use guidance is provided. There is no mention of when to choose this over sibling add_*_widget tools, nor when update_embed_widget would be the appropriate alternative. The conditional relationship between embed_type and link_url (link_url only for URL/IFRAME modes) is left for the agent to infer from the schema.

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

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

The description reveals that the widget initially shows a demo target until pointed at a saved goal, that it returns widget_id, and that layout matches the editor's Goal card. These behaviors go beyond the annotations (readOnlyHint=false, destructiveHint=false) and help the agent predict side effects and follow-up actions.

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

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

Three sentences, front-loaded with the core action, then return value/workflow, then rationale and layout. No filler; each sentence adds distinct value.

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

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

For a create-style tool with a documented output schema and fully described parameters, the description covers the widget's initial state, follow-up call, and layout behavior. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents page_id, client_id, and source_id. The description adds context about the goal carrying its own query/target/comparison but doesn't add parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Add a Goal widget to a page') and immediately characterizes the widget as a progress gauge with a demo target. It distinguishes this from sibling add_*_widget tools by explaining that the goal carries its own metric query, target, and comparison, so no metrics/dimensions are needed.

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

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

It provides clear context for when to use it: to add a Goal widget, and it routes the next step to update_goal_widget with an id from list_goals. It doesn't explicitly state when not to use it or name alternatives, but the workflow and 'no metrics or dimensions' note distinguish it from data widgets.

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 description adds useful behavioral context by noting that position, width, and height use sensible defaults, which is beyond the schema. However, it does not explain the creation side effect, required references, or any other behavioral nuance; annotations are minimal but consistent.

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 concise two-sentence definition with no redundant text. The main purpose is stated first, and the useful defaulting behavior is added in the second sentence without wasting 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?

Given a fully described schema and an output schema, the description is nearly complete for invoking the tool correctly. The main gap is the absence of usage guidance relative to sibling tools, but this is partially covered by the tool name and 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 input schema fully documents each parameter. The description itself adds no parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action and resource: 'Add an image widget to a page.' This distinguishes it from other sibling add_*_widget tools by naming the widget type and target without ambiguity.

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 add_asset_to_page, add_embed_widget, or update_image_widget. It does not mention prerequisites or exclusions; usage is only implied by 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?

With only generic annotations (readOnlyHint false, destructiveHint false), the description carries the burden and does it well. It discloses the important behavioral traits: no datasource, no fetching, inline content, defaulting to 0 when value is omitted, and that dimensions match the editor's card. This adds substantial context beyond the annotations.

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

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

Three sentences deliver meaningful, non-redundant information. The action is front-loaded, the key differentiator is stated early, and every sentence adds value—examples, behavior, and layout context.

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 schema fully documents all parameters and required IDs, and an output schema exists for return values, the description covers the remaining context: what the widget is, how it behaves, how to set or omit the value, and how to update it later. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description goes beyond the schema by explaining the 'value' parameter's semantics with concrete examples, the default-to-0 behavior, and the later update path, which helps the agent understand how to use the parameter correctly.

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

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

The description clearly states the verb and resource: 'Add a Static Value widget to a page', with explicit examples of the value types it accepts. It also distinguishes this widget from other cards by emphasizing 'has no datasource and never fetches' and 'its content is inline', making it easy to separate from sibling add_*_widget tools.

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

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

The description gives clear context by contrasting this widget with 'the other cards' and explains how to set the value now or later via update_static_value_widget. It does not explicitly name alternative tools or state exact when-not-to-use conditions, so it stops just short of full exclusion guidance.

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

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

Annotations contribute readOnlyHint=false and destructiveHint=false, so the description is not required to re-state that this is a mutating but non-destructive operation. The description adds useful behavior context: Markdown is rendered and position/width/height have sensible defaults. It does not disclose side effects such as creation behavior, response contents, or permission requirements, so it stays at a moderate score.

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 no filler. The primary purpose is front-loaded, and the Markdown capability and default-layout behavior are stated efficiently.

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 create operation with a fully documented input schema and an output schema present, the description covers the essential behavior: what is added, what content format is supported, and the fact that layout defaults require no parameters. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already thoroughly documents text, page_id, client_id, and source_id. The description adds little beyond repeating Markdown support and mentioning layout defaults that are not actual parameters. This is a solid 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?

Description uses a specific verb-resource pair ('Add a rich-text widget to a page') and explicitly mentions Markdown support, which differentiates it from sibling add_*_widget tools. The scope is immediately clear.

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

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

The description gives clear context for when to use this tool: when adding a rich-text/Markdown widget to a page. It does not explicitly name alternatives or exclusion conditions, but the rich-text and Markdown cues are enough to route an agent correctly among the widget-add 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?

Annotations establish that the operation is mutating but non-destructive; the description adds that position, width, and height use sensible defaults. However, it does not explain what those defaults are, whether placement could overlap existing content, or any side effects, and it references fields not present in the schema.

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

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

The description is one short sentence with the action front-loaded. However, 'sensible defaults' is vague, and the mention of non-existent position/width/height parameters adds minor confusion, so it is not maximally clean.

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 and the input schema includes helpful source hints like 'from list_pages' and 'from list_clients'. Still, the description's inconsistency about position/width/height and its lack of details on default behavior leave gaps for an agent deciding whether and how to invoke this tool.

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

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

The schema has 100% coverage for all five parameters, providing a baseline of 3. But the description mentions 'position, width, and height' which are not in the schema, potentially misleading agents into expecting controls that do not exist. This mismatch reduces the value the description adds 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 clearly states the action (Add) and the resource (a title widget) plus the target (a page), which distinguishes it from sibling add_*_widget tools. It is concise and immediately understandable, though it does not explicitly differentiate itself from add_text_widget or others.

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 about when to use this tool versus the many sibling add_*_widget tools, nor any exclusions or prerequisites. The mention of 'sensible defaults' implies a use case but does not specify when defaults are appropriate or when another widget tool should be chosen.

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 description adds meaningful behavioral context beyond the annotations by clarifying that archiving is reversible ('not away') and that the operation cascades to widget rows. This is valuable given destructiveHint=true, as it reassures the agent about recoverability.

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

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

The description is two sentences long and front-loads the core action, then adds the most important behavioral nuance and relevant sibling tools. Every sentence earns its place with no redundancy or filler.

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

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

For a single-parameter tool with a documented input schema, output schema, and safety annotations, the description covers the key decision factors: what is affected, that it is recoverable, and how to view or reverse it. Nothing essential is missing.

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

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

Schema coverage is 100% with one parameter, and the schema already documents 'id' as 'Asset ID to archive (from list_assets).' The description does not add new parameter-level detail, so the baseline score 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: 'Archive a saved section and its widget rows.' It also clarifies the scope of the operation beyond the title by noting widget rows are included, which helps distinguish it from other archive_* tools targeting different entity types.

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

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

The description provides clear context by explaining what happens after archiving and explicitly names the relevant companion tools: 'list_archive shows it and restore_from_archive brings it back.' It lacks an explicit exclusion statement ('use this instead of delete...'), but the lifecycle context is sufficient for an agent to select it appropriately.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds meaningful behavioral detail: the automation is stopped, moved to archive, remains visible via list_archive, and can be restored with rescheduling. This clarifies the reversible nature of the operation and is not available from annotations alone.

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

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

The description is two short sentences with no filler. The primary action and effect are front-loaded first, followed by the key recovery 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?

The description, combined with fully documented parameters and an output schema, gives an agent everything needed to understand the operation, its consequences, and how to reverse it. It also orients the tool within the archive/restore lifecycle.

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 two parameters (id and parent_id) are already well documented with their source lists. The description adds no additional parameter-level semantics, which matches the baseline score of 3 for a fully covered schema.

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

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

The description uses a specific verb and resource: "Archive an automation" and immediately states the key effect, "stopping its scheduled deliveries." It also distinguishes this from destruction by clarifying "it goes to the archive, not away" and naming list_archive and restore_from_archive.

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

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

The description provides clear usage context: use archive to stop scheduled deliveries while preserving the automation for later restoration. It names the relevant recovery tools but does not explicitly contrast with the sibling pause_automation or state when not to use this tool, so it falls short of full exclusion guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known; the description adds value by clarifying the archiving behavior: the metric is moved to an archive, remains visible in list_archive, and can be restored. This nuance—recoverable, not deleted—goes beyond what annotations provide. No contradiction 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 entire description is one tightly written sentence that front-loads the verb and resource, then immediately explains the non-permanent consequence. Every phrase earns its place—no filler, no repetition of title or schema.

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

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

For a one-parameter tool with an existing output schema and annotations covering the safety profile, the description covers the key behavior an agent needs: what archiving does, how it can be seen again, and how it can be undone. Nothing essential is missing 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% and the sole id parameter has a helpful schema description naming its source (list_calculated_metrics). The tool description itself adds no additional parameter-level details beyond referencing 'by ID', so the baseline 3 applies—schema already 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 action (archive) and resource (calculated metric) plus the ID identifier, and immediately clarifies the semantics by contrasting with permanent deletion. It also references list_archive and restore_from_archive, making it easy to distinguish from delete/update operations even among many archive_* siblings.

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

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

The description gives clear context on the tool's effect—items are recoverable and visible in list_archive—which helps an agent decide between archiving and deletion. It does not explicitly enumerate when not to use it or compare to other archive tools, but for this single-resource action the guidance is sufficient.

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

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

Annotations already flag destructiveHint=true, and the description adds meaningful nuance: it clarifies that destruction is actually an archive, not a permanent delete, and it discloses exactly what gets archived (reports, exports, automations) and how to reverse it. This goes beyond what annotations alone convey and does not contradict them.

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 front-load the primary action and scope, then add the key distinction from permanent deletion. There is no filler or repetition of schema details, so every sentence earns its place.

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

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

For a single-parameter tool with an output schema and annotative safety info, the description covers the critical operational details: what happens to the client's related resources and that the action is reversible. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, and the id parameter is already well documented in the schema as 'Client ID to archive (from list_clients)'. The tool description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific action ('Archive a client by ID') and the precise scope of side effects ('with its reports, exports and automations'). It also distinguishes this from other archive tools by emphasizing the archive is recoverable rather than permanent, and the singular 'by ID' separates it from the plural sibling archive_clients.

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

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

The description gives clear context by naming the lifecycle counterparts list_archive and restore_from_archive, implying the tool is for reversible, client-scoped archiving. It does not explicitly call out when to use archive_clients or individual archive_* tools instead, 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 already declare destructiveHint=true and readOnlyHint=false, so the description adds meaningful context by clarifying that archiving is reversible: clients go to the archive and can be recovered via restore_from_archive. This goes beyond the annotation's blunt 'destructive' flag and prevents the agent from assuming permanent deletion.

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, no filler, with the core action front-loaded and the important reversibility nuance stated immediately after. Every phrase earns its place.

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

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

For a single-parameter batch operation with an output schema, destructiveHint, and reversibility info, the description covers everything an agent needs to select and invoke the tool correctly. The recovery references provide the surrounding context that makes the outcome predictable.

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

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

The single parameter ids is fully documented in the schema with 'Array of client IDs to archive (from list_clients)', so the description need not repeat it. The description adds only the generic 'by ID' phrase, which is already implied by 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 ('Archive'), a resource ('clients'), and a clear scope ('several by ID in one call'), distinguishing it from the singular archive_client sibling. The phrase 'not away' clarifies that this is an archive operation, not deletion.

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 batch usage ('several clients by ID in one call'), which faintly contrasts with archive_client, but it never explicitly says when to choose one over the other or when not to use it. It also does not mention the relationship to list_archive or restore_from_archive as a lifecycle step.

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 description adds meaningful behavior beyond the annotations: it explicitly reassures that archiving is not deletion ('not away') and points to the restoration path. This is valuable context that complements the destructiveHint=true annotation and clarifies the practical consequence of the action.

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 deliver the core action, the reversible nature of the operation, and the related navigation/restore tools with no wasted words. The most important information is front-loaded.

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

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

For a single-parameter tool with an output schema and lifecycle-related sibling tools, the description is complete: it tells what the tool does, where the archived item goes, how to find it, and how to reverse the action. 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?

The schema already fully documents the only parameter ('id' with a clear source hint 'from list_custom_data'), so the description adds no new parameter-level meaning. The phrase 'by ID' reinforces the schema, but the schema carries the semantic weight, so the baseline score 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 names a specific verb ('Archive'), a specific resource ('a custom-data dataset'), and the mechanism ('by ID'), so an agent can immediately identify the operation. It also distinguishes this from the many sibling archive_* tools by explicitly naming the custom-data resource type.

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

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

The description gives clear lifecycle context: the dataset moves to the archive, is visible via list_archive, and can be recovered via restore_from_archive. It does not explicitly state exclusions or name a non-archive alternative, but the intended use case is well implied and the sibling resource names make differentiation straightforward.

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 mark destructiveHint=true, so the description's value is in explaining that archiving is not permanent destruction. It adds useful behavioral context by stating the record remains accessible and reversible, which goes 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 concise sentences with no filler. The core action is front-loaded, and the clarifying contrast with permanent deletion and references to list_archive/restore_from_archive each earn their place.

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

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

For a single-required-parameter tool with an output schema present and annotations covering safety, the description is complete. It explains the operation, the archive semantics, and the recovery path, so an agent has enough to call it correctly.

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

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

Schema coverage is 100% and the id parameter already includes 'Export ID (from list_exports)'. The description only echoes 'by ID' and adds no new semantic detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific action ('Archive a PDF export record by ID') and names the resource (PDF export) and the operation (archive). It also distinguishes this from permanent deletion by clarifying 'It goes to the archive, not away', which helps differentiate it from destructive delete-type siblings.

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

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

The description provides clear context: the tool archives an export, and archived items are visible via list_archive and recoverable via restore_from_archive. This implies when to use it and names the inverse alternative, though it does not explicitly state conditions for when not to use it or compare with other archive_* tools.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=true. The description adds valuable context beyond that by stating the goal 'goes to the archive, not away' and that list_archive/restore_from_archive can show and restore it. This clarifies the real-world effect of the destructive hint without contradicting it.

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 one efficient sentence that front-loads the action ('Archive a goal by ID') and then adds a useful clarifying clause about recoverability and related tools. Every word earns its place, with no filler or redundancy.

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

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

For a single-parameter tool with an output schema and annotations already defining read-only and destructive hints, the description covers the key behavioral nuance of archiving. It could optionally mention side effects on active lists or permissions, but the provided context is sufficient for correct selection and invocation.

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

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

Schema coverage is 100% and the single `id` parameter is already described as 'Goal ID (from list_goals)'. The description adds only the phrase 'by ID', which doesn't meaningfully extend the schema's parameter documentation, so the baseline score 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: 'Archive a goal by ID.' It also names related tools (list_archive, restore_from_archive) and clarifies that the goal is recoverable, which helps distinguish archive from a permanent delete. It stops short of explicitly contrasting with other sibling tools, but the resource and action are clear.

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

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

The description implies when to use this tool: to put a goal into the archive while keeping it recoverable. However, it never explicitly says 'use this when you want to remove from active view but not permanently delete' or names situations where a different tool should be used. Usage context is conveyed through behavior rather than direct guidance.

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

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

Annotations mark destructiveHint=true, but the description adds important context: the file is not deleted, it is moved to archive and can be restored, with permanent deletion only when explicitly done. This goes beyond annotations and clarifies the exact behavioral outcome.

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 concise sentences that front-load the action and clarify the non-destructive nature. Every sentence adds value and there is no waste.

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

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

For a single-parameter tool with full schema coverage and an output schema, the description explains the full lifecycle and related tools, making it complete 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 already fully documents the only parameter (id) with source guidance ('from list_media'), and the description does not add further parameter details. With 100% schema coverage, 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 clearly states the action (archive) and resource (media file), and clarifies the semantics with 'It goes to the archive, not away' and mentions related tools (list_archive, restore_from_archive). It distinguishes from deletion and other archive tools.

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

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

It explains the behavior and points to related tools, implying when to use this tool for reversible archiving. However, it does not explicitly compare to other archive variants like archive_media_files or deletion tools, so it misses a direct alternative comparison.

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 destructiveHint=true, but the description clarifies this is reversible archiving, not permanent deletion, which is valuable context beyond the annotation. It also notes the batch nature ('in one call'). No contradictions, but it doesn't cover failure modes or partial success, so not a perfect 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?

Two sentences, no fluff. The core action is front-loaded, and the clarifying note about reversibility is concise and relevant. Every word earns its place.

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

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

For a batch archive tool with an output schema present, the description covers the effect, reversibility, and related tools. An agent can decide to use it and understand the outcome without missing critical information.

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 has 100% coverage for the single 'ids' parameter, including its origin (list_media). The description adds only that the operation is by ID and batch-oriented, which slightly reinforces the schema but doesn't introduce new meaning. Baseline 3 is appropriate.

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

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

States a specific verb+resource (archive media files) and scopes it to multiple files in one call, which distinguishes it from the singular archive_media_file sibling. The phrase 'by ID' adds precision, and the sentence is unambiguous.

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

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

Explains the archival semantics ('not away') and references list_archive and restore_from_archive as complementary tools. It does not explicitly name archive_media_file as the alternative for a single file, but the plural scope implies it, so the usage context is clear.

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

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

Annotations mark destructiveHint=true, but the description adds meaningful context beyond that: it clarifies the archive is reversible ('goes to the archive, not away'), that pages and widgets remain attached, and that list_archive and restore_from_archive are the recovery paths. This enriches the agent's understanding of the operation's effects.

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. The core action is front-loaded, and the clarifying details about persistence and recovery are added without waste.

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

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

The description fully covers what an agent needs to know for a single-parameter archive operation: the target, the effect on contents, and how to reverse it. With an output schema present and no nested complexity, nothing essential is missing.

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

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

Schema coverage is 100% and the schema description for report_id already specifies it comes from list_reports. The tool description adds no further parameter details, so baseline 3 applies.

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

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

States a specific verb and resource: 'Archive a report by ID.' It also clarifies scope by noting pages and widgets stay attached, and names related sibling tools (list_archive, restore_from_archive) that make its purpose distinct from other archive tools.

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

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

The description implies usage for reports and explains the reversible nature, but does not explicitly contrast with sibling archive tools like archive_asset or archive_reports (plural). It gives context on what happens after archiving but no explicit when/when-not guidance.

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

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

Annotations already flag destructiveHint=true, and the description adds meaningful context that archiving is reversible and not permanent deletion, pointing to the complementary tools for viewing and restoring. This goes beyond the structured annotation and helps the agent understand the full impact of the operation.

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

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

Two short sentences with no wasted words. The purpose is stated first, followed by a clarifying note about the effect. It is well-structured and immediately understandable.

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 one-parameter tool with an output schema present, the description covers the action, the scope, and the behavioral nuance (reversibility). An agent has everything needed to decide when to call it and what to expect, without needing to inspect the schema.

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

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

The sole parameter report_ids is fully described in the schema with 'Report IDs to archive (from list_reports)'. The tool description adds no further detail about the parameter, so with 100% schema coverage 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 clear verb (archive), resource (reports), and scope (multiple reports by ID in one call). It distinguishes itself from the singular sibling archive_report by emphasizing batch operation, and clarifies the semantic that items are not deleted ('not away').

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

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

It clearly indicates the tool is for archiving multiple reports in a single call, and the second sentence implies when it is appropriate by noting that archived reports remain accessible via list_archive and restore_from_archive. However, it does not explicitly say to use archive_report for single reports, though the plural/singular distinction is implied.

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

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

Annotations already mark this as destructive (destructiveHint: true), and the description adds valuable context beyond that: the template is moved to an archive rather than permanently removed, and it can be recovered via restore_from_archive. This directly addresses a common misunderstanding about permanent deletion and gives the agent a clearer mental model of the side effects.

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 tightly written sentences. The first states the action; the second clarifies the outcome and recovery path. No filler or redundant phrasing; every word earns its place.

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

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

For a simple one-parameter tool with an output schema and clear annotations, the description is complete. It explains the destination (archive), the verification mechanism (list_archive), and the reversal path (restore_from_archive), giving an agent everything needed to call it safely 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 only parameter, id, is fully documented in the schema with 'Template ID to archive (from list_templates).' The tool description merely repeats 'by ID' without adding new details such as format, validation, or source. Since schema coverage is 100%, the baseline of 3 applies; the description contributes no additional parameter insight.

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: 'Archive a template by ID.' It also clearly distinguishes archiving from permanent deletion with 'It goes to the archive, not away,' and references related tools (list_archive, restore_from_archive) that make the intent unmistakable.

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

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

The description provides clear context about what happens after archiving and points to list_archive and restore_from_archive as related lifecycle operations. It does not explicitly rule out using archive_* tools for other resource types, but the template-specific scope is obvious from the name and context.

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

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

Annotations already declare destructiveHint=true, but the description adds valuable behavioral context: the fallback behavior for reports, and reversibility via list_archive/restore_from_archive. This goes beyond just saying 'destructive' and helps the agent understand consequences, exceeding what annotations alone provide.

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 main action, followed by consequences and reversibility. Every sentence adds distinct information with zero waste. The structure efficiently communicates the core behavior in under 30 words.

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

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

For a single-parameter tool with destructive annotation and an output schema, the description covers all needed aspects: what it does, what happens to dependent reports, and how to reverse it. It even names the relevant sibling tools (list_archive, restore_from_archive). Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% for the single 'id' parameter, and the schema description ('Theme ID to archive (from list_themes)') already explains its source. The description's 'by ID' adds no additional semantics. Per calibration, baseline 3 is appropriate when 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 (archive) and resource (theme) with the parameter (by ID). It distinguishes from sibling archive tools by naming the resource and explains the key behavioral distinction from deletion: 'It goes to the archive, not away — list_archive shows it and restore_from_archive brings it back.' This clearly separates it from other archive_* tools and any hypothetical delete operation.

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: reports using the theme fall back to default and it can be restored. This implies when to use (to temporarily remove a theme while preserving recoverability). It does not explicitly state when NOT to use or name an alternative like delete, but the context is sufficient for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' It goes beyond the annotations by explaining what the audit covers: connected data sources, automation state, and specific issue types like no data sources or paused automations.

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

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

The description is two sentences, front-loads the core action, and every clause adds information about what the tool does or does not do. The 'Read-only.' tag is compact and reinforces the safety profile without 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 single-parameter, read-only tool with an output schema, the description is complete: it states the input expectation implicitly through the schema, describes what the audit includes, and warns about read-only behavior. There are no missing concepts an agent would need to invoke it correctly.

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

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

Schema coverage is 100% for the single parameter, and the schema description 'Report ID to audit (from list_reports)' is already informative. The description adds no additional parameter-level meaning, so it meets the baseline but does not exceed it.

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

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

The description names a specific action ('Audit'), the resource ('report or dashboard'), and the concrete outputs: connected data sources, automation state, and likely issues. This clearly distinguishes it from sibling tools like connected_datasources or list_automations, which only cover part of this functionality.

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

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

The phrase 'Audit a report or dashboard' plus 'flag likely issues' gives clear context for when to use this tool: as a health check rather than a raw data retrieval. It does not explicitly name alternative tools or exclusion cases, so it falls just short of full 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 description discloses substantial behavior beyond the annotations: widgets are re-fetched and saved, widgets on custom ranges keep them, rolling presets are stored and re-resolved, and the re-fetch is background. This adds rich context that the annotations (readOnlyHint false, destructiveHint false) do not provide.

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

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

Three sentences with no wasted words. The main action is front-loaded, and each sentence adds essential behavioral detail without bloat.

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

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

For a tool with a nested date_range object and an output schema, the description covers the key usage context: effect on widgets, background re-fetch, and how to retrieve results. Nothing needed to call it correctly is missing.

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

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

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining how the date_range object behaves (rolling presets, custom range preservation), which complements the schema without redundancy.

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 the specific verb 'Set' and the resource 'period a report covers', and goes further to explain the re-fetch and saving behavior, which clearly distinguishes it from update_report and other tools. The purpose is unambiguous.

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

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

It clearly describes when to use the tool (to change a report's date range) and even directs the agent to call get_widget_data to read results. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about demo data vs real data, but does not disclose any specific behavioral details such as pagination, ordering, or response structure beyond what the output schema already 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?

Two concise sentences with no wasted words. The main purpose is front-loaded, and the additional note about widget connectivity earns its place by clarifying the tool's relevance.

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

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

The tool is simple, has no parameters, and has an output schema that covers the return format. The description provides the purpose and a relevant domain context, so nothing an agent needs to call it correctly is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter semantics, and there are no parameters to clarify. The empty schema is fully sufficient.

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

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

The description clearly states the verb ('List') and the specific resource ('datasource connections this account has made'). It distinguishes from likely siblings like 'datasources' by emphasizing connections rather than datasources themselves, and adds a domain note about widget behavior that clarifies why this tool exists.

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 a clear use case: verifying that a datasource is connected so that widgets pull real data instead of demo data. This provides context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the result is a total count scoped to the account, which is useful but does not go beyond that minimal behavioral context.

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

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

The description is a single efficient sentence with no filler. The key action, resource, and scope are all front-loaded and immediately understandable.

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 count operation with an output schema present, the description is complete. An agent has everything needed to invoke the tool correctly without additional 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?

There are zero parameters, so per the rubric the baseline is 4. The description adds no parameter details because none exist, and no parameter documentation is needed for invocation.

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

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

The description uses a specific verb ('Get') and identifies the exact resource ('total count of clients') and scope ('for the account'). It clearly distinguishes this tool from the sibling list_clients, which would return client records rather than an aggregate count.

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

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

The description clearly conveys when to use this tool: when a count of clients is needed, not a listing. It does not explicitly name alternatives or exclusion criteria, but the zero-parameter aggregate nature makes the usage context obvious.

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 provide only broad hints (readOnlyHint false, destructiveHint false). The description adds meaningful behavioral detail: each widget is copied with a fresh id, and type/datasources are derived from the selection. This goes beyond the annotations by explaining exactly what happens to the widget configuration, making the tool's behavior predictable.

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

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

Two sentences with no filler. The first sentence front-loads the action and copy semantics; the second provides a useful pointer to the downstream tool. The editor analogy earns its place by anchoring the behavior in a familiar workflow.

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 readOnly/destructive hints provided, the description covers the essential behavior and copy semantics while referencing the next-step tool. It does not discuss permissions or preconditions, but for this complexity level and schema richness it is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema—'derived from what you picked' loosely echoes the widget_ids parameter, but it doesn't clarify any parameter syntax, constraints, or interactions beyond what the schema already documents.

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

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

The description states a specific verb and resource: save widgets as a reusable section, and clarifies the behavior with the editor analogy. It also names the complementary sibling add_asset_to_page, distinguishing the creation step from the later placement step. This is unambiguous and sets the tool apart from related siblings like create_template or duplicate_asset.

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

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

The description gives clear context for when to use the tool (to create a reusable section from selected widgets) and explicitly points to add_asset_to_page for the next step. It does not list exclusions or conditions for choosing this over other creation tools, but the context is strong enough to guide an agent.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating operation. The description adds the side effect that a custom payload is saved as a new named email template, which is useful behavioral context beyond the annotations. It does not cover rate limits or auth requirements, but with annotations present, the baseline is met and slightly exceeded.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the two usage modes are presented in a compact, logical order. Every clause 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 13 parameters, a nested object, and an output schema, the description covers the critical branching logic (custom vs. existing template) and references the required lookup tools. It does not explain the frequency/day/time combinations, but the schema and required fields carry that load. The presence of an output schema means return values are already specified. Missing a few edge-case clarifications, but adequate for a complex tool.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds value by explaining the conditional relationship between template_id and the custom object, and by pointing to list_email_templates and list_email_senders as sources for valid IDs. This goes beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb and resource ('Create a new automation') and immediately clarifies the two supported modes (existing template+sender vs. inline custom template). This clearly distinguishes it from siblings like update_automation, archive_automation, or test_automation by stating exactly what it creates.

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

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

The description gives explicit guidance on when to use each path: pick an existing template/sender by id from the listed sources, or pass template_id:'custom' with a custom payload. It does not state exclusions (e.g., when not to use this tool), but the creation intent is unambiguous given the sibling list. It could mention that updating an existing automation should use update_automation, but that's implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the agent knows this is a non-destructive, closed-world write. The description adds only the conceptual nature of what is created; it does not mention dependencies (referencing existing metric ids from describe_datasource) or side effects. With annotations carrying the safety profile, this is adequate but thin.

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

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

A single, front-loaded sentence with the verb+resource leading and the defining clause trailing; nothing is padded. It is tightly written, though the trailing clause is mildly redundant with the title.

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

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

An output schema exists, so return values need not be explained, and the schema fully documents parameters. However, for a create tool with a complex nested formula, the description supplies no prerequisites or workflow context (e.g. that metric/datasource ids come from describe_datasource). Minimal but passable given the rich 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% and the formula parameter even ships a worked CTR example, so the schema does the heavy lifting. The description's phrase 'formula over other metrics' gestures at the formula semantics but adds no syntax, token ordering, or format detail beyond the schema. Baseline 3 is correct.

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

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

States a specific verb (Create) and resource (calculated metric), and the em-dash clause defines what a calculated metric is (a custom KPI from a formula over other metrics). This distinguishes it from widget siblings like add_calculated_metric_widget. It stops short of naming the nearest alternatives (update_/duplicate_calculated_metric), so it is clear but not sibling-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?

Usage is only implied: the agent can infer you use this when you need a custom KPI built from a formula. There is no explicit when-to-use vs update_calculated_metric/duplicate_calculated_metric guidance and no prerequisites (e.g. that the underlying metrics must exist). Implied-but-unstated usage maps to a 3.

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 description adds no behavioral detail beyond what annotations already convey: readOnlyHint=false signals mutation, and destructiveHint=false suggests a non-destructive creation. Nothing is disclosed about side effects, duplicate handling, permissions, or what happens after creation.

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

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

The description is extremely concise and front-loaded with the verb, containing no filler. However, it mostly restates the tool name and title, so while it is efficient, it does not use its brevity to add distinguishing value beyond 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?

The input schema covers all parameters and an output schema is present, so the agent can invoke the tool mechanically. However, the description does not address the ambiguity with create_client_with_report or explain what creating a bare client means in context, leaving the description incomplete for tool 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 description coverage is 100%, so the schema already explains all six parameters, including currency format and the source of folder/manager IDs. The description itself contributes no parameter detail, so the baseline score of 3 for high schema coverage 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 clear operation and resource: 'Create a new client.' It clearly distinguishes the tool from update_client and archive_client, but it does not differentiate it from the sibling create_client_with_report, so it is not fully unambiguous.

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

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

No guidance is provided about when to use this tool versus create_client_with_report or other client-related tools. There is also no mention of prerequisites such as obtaining folder or manager IDs from list_folders/list_users; the description simply restates the operation with no contextual routing.

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

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

Annotations already show this is a write operation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds valuable behavioral detail beyond annotations, such as the resolution order and the guarantee that 'with neither, a matching Starter template... is cloned (never a blank report).' No contradiction with annotations.

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

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

The description is three sentences with no filler. It front-loads the primary purpose, then explains the branch logic and how to select a template. Every sentence contributes to correct use.

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

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

For a tool with output schema and annotations, the description covers the main steps and resolution logic adequately. A minor gap is that it does not specify behavior when both template_id and blank:true are provided simultaneously, which could cause ambiguity. Otherwise it is 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 coverage is 100%, so the baseline is 3. The description adds critical meaning beyond the schema by explaining how template_id, blank, and type interact: cloning, empty creation, and fallback behavior. This helps an agent understand the combined semantics rather than just individual field meanings.

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

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

The description starts with a specific verb and resource: 'Create a new client and its first report or dashboard in one step.' This clearly distinguishes it from sibling tools like create_client, create_report, and create_report_from_template by emphasizing the combined action.

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

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

The description gives concrete guidance on how the first report is resolved: 'template_id clones that template; blank:true creates an empty report; with neither, a matching Starter template of the given type is cloned.' It also directs users to list_templates for a specific style. However, it doesn't explicitly state when to use create_client or create_report instead, only implies the one-stop purpose.

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 readOnly=false, destructive=false, openWorld=true, so the mutation and openness profile is already covered. The description adds genuinely new behavior: the discover-then-submit call sequence, and the subtle upsert semantics where re-using an existing name overwrites that connection's credentials rather than erroring. It stops short of describing failure modes or required role/permissions, which keeps it below 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 action, then the call pattern, then the exclusion, then the follow-ups — a logical order with no filler sentences. Slightly dense and the 'connect panel's credential form, as a tool' framing is mildly wordy, but every sentence carries routing or behavioral 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 description fills the remaining gaps for a 3-param nested-object mutation: discovery flow, upsert behavior, scope exclusions, and the correct follow-up tools. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents name, credentials, and datasource_id. The description adds usage semantics the schema cannot express — calling with only datasource_id is a discovery mode that returns the required credential keys, and credentials must be keyed as that listing dictates.

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 datasource connection) and immediately frames it as the connect panel's credential form exposed as a tool, which tells an agent exactly what this does. The two-phase call pattern and the OAuth exclusion distinguish it clearly from siblings like link_datasource and test_connection.

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

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

Explicit when-to-use (credentials-based datasources), explicit when-not (Google/Meta/LinkedIn sign-in datasources 'cannot be created here and say so'), and explicit alternatives for follow-up work (link_datasource to attach a client, test_connection to verify). Nothing is left to inference.

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

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

Annotations already indicate this is not read-only and not destructive; the description is consistent with those hints. It adds the useful 10,000-row constraint but does not disclose side effects, validation behavior, or failure modes. With annotations covering the safety profile, 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?

The description is a single, front-loaded sentence with no filler. It states the action, object, source, and key limit efficiently.

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 straightforward creation tool with fully documented parameters and an output schema, the description plus schema provides enough to invoke it correctly. The only minor gap is the lack of explicit guidance on what happens if the row limit is exceeded, though the limit itself is stated.

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 provides descriptions for all five parameters, so the description does not need to repeat them. It adds high-level context about parsed CSV rows and the row cap, but no additional per-parameter meaning beyond what the schema already offers.

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

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

The description states a specific verb ('Create'), a specific resource ('custom-data dataset'), and the input source ('parsed CSV rows'). This clearly distinguishes it from siblings like create_custom_data_widget, which create widgets rather than the dataset itself.

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

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

The phrase 'from parsed CSV rows' implies when this tool is appropriate, and the 10,000-row limit sets a boundary. However, it does not explicitly name alternatives or state when not to use it, leaving the routing decision to inference.

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

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

Annotations indicate this is not read-only and not destructive, but the description adds no behavioral context beyond the act of creation. It does not mention uniqueness requirements, where the folder is created, or any side effects; it also does not contradict the annotations.

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

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

The description is a single, front-loaded sentence with no filler. However, it almost exactly repeats the title, so it is concise but adds little informational value beyond that already visible in the tool metadata.

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 large set of sibling tools, the description is too thin to fully orient the agent: it does not clarify what a client folder is, how it relates to clients, or when creating one is appropriate. The output schema exists but is not shown, and the description does not explain the expected 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 schema fully documents the single 'name' parameter with 100% coverage, so the description does not need to repeat it. The description adds no extra semantic detail about the parameter, but the schema already carries the load, justifying the baseline score.

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

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

The description uses a specific verb ('Create') and resource ('a new client folder'), making the core action clear. It does not distinguish this from sibling tools like create_client or create_asset, but the resource name is specific enough to avoid major ambiguity.

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 about when to use this tool versus alternatives such as create_client, update_folder, or move_client_to_folder. It also does not explain what a 'client folder' is for, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no mention that the goal is persisted, that null date_range is the normal stored case (the schema carries that), or what side effects creation has. With annotations in place the bar is lower, but there is still no added behavioral context.

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

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

A single tight sentence with the core concept front-loaded and no wasted words. It is efficient, though its brevity is closer to under-specification than deliberate economy.

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 tool — 8 params, nested query objects, enums, an output schema — and the description does not prepare the agent for that complexity or the id-lookup workflow the schema references (describe_datasource, list_clients). The 100%-documented schema and output schema carry most of the load, so the definition is adequate but incomplete.

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 rich nested parameter docs, so the baseline is 3. The description's 'target value + comparison for a saved metric query' merely paraphrases the required target_value/operator/query fields and adds no syntax or sourcing detail 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 ('Create') and resource ('goal'), and even defines what a goal is — 'a target value + comparison for a saved metric query' — which is useful domain grounding. It does not differentiate itself from siblings like duplicate_goal, update_goal, or add_goal_widget, 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 statement of when to use this tool versus alternatives (duplicate_goal, add_goal_widget), and no prerequisites called out — e.g. that metric ids come from describe_datasource or client_id from list_clients, despite both being needed to call it successfully.

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 indicate this is a write operation (readOnlyHint=false), so the description's disclosure of the default append behavior adds value. However, it does not mention other behavioral aspects such as visibility defaults (covered in schema) or any side effects. The description is minimal but not misleading.

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

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

The description is extremely concise, using only two sentences with no filler. The primary purpose is front-loaded, and the default behavior is stated efficiently. Every word earns its place.

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

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

Given the rich schema (100% coverage) and presence of an output schema, the description is adequate for an agent to invoke the tool correctly. It covers the core action and default behavior, while the schema handles parameter details. It does not mention prerequisites (e.g., that the report/template must exist), but this is implied and covered by source_id guidance.

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 all parameters well-described. The description adds only the note about appending by default, which is already implied by the position parameter's description. Thus, it provides minimal additional semantic value 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 ('Add a page') and resource ('report or template'), which clearly distinguishes this from sibling tools like update_page, delete_page, and list_pages. It also conveys the default behavior of appending at the end, making the purpose unambiguous.

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

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

The description implies usage for adding pages to existing reports or templates but does not explicitly mention when not to use it or name alternatives. While the context is clear enough, there is no guidance on how it differs from other creation tools like create_report or create_template, leaving room for confusion.

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 indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds useful context: presentation toggles have server defaults when omitted, and layout is constrained (dashboard always grid). However, it does not disclose other behavioral aspects such as error handling, idempotency, or authentication requirements. It adds moderate value beyond annotations, so a 3 is appropriate.

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

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

Two sentences, no filler. The core purpose is front-loaded, and the layout constraint and default behavior are stated efficiently. Every word earns its place. The description is appropriately sized for the tool's complexity.

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

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

Despite having 19 parameters and nested objects, the description is minimal but the schema carries the heavy lifting with 100% coverage. The description adds the essential cross-cutting context (layout rules, server defaults) that the schema cannot express at the property level. An output schema exists, so return values do not need to be described. For a creation tool with this complexity, the description is reasonably complete, though it could mention that client_id and template_id reference list_clients and list_templates (though those are already in the schema).

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

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

Schema description coverage is 100%, so all 19 parameters are documented in the schema. The description adds extra meaning by clarifying the layout parameter's behavior (dashboard always grid) and the default behavior of presentation toggles when omitted. This goes beyond the schema's individual property descriptions, which is valuable given the number of boolean toggles. This justifies a 4 rather than a 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?

The description states a specific verb ('Create'), a clear resource ('a new report or dashboard for a client'), and adds distinguishing constraints (report can use grid or canvas, dashboard is always grid). It is immediately distinguishable from siblings like create_report_from_template, duplicate_report, and create_client_with_report without inspecting their 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?

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that create_report_from_template should be used when cloning a template, or that duplicate_report is for copying an existing report. The only implied guidance is that this is the generic create tool, but that is not stated. An agent could confuse it with create_report_from_template because both create reports.

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 description discloses that cloning copies pages + widgets, which reveals the operation's scope beyond the annotations' readOnlyHint=false/destructiveHint=false. This tells the agent the new report will inherit the template's structure. It does not contradict any annotation. Minor gap: it doesn't specify behavior on type mismatch, though the schema's 'must match the template' partially covers this.

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

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

Two sentences with zero waste. The core action is front-loaded in the first sentence, and the second sentence delivers the prerequisite workflow plus a concrete filter example. Every clause 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 the output schema exists (so return values need no explanation), the description covers purpose, prerequisite workflow, and filtering guidance. All four required params are documented in the schema. The only minor omission is explicit mention that type must match the template's type, though this appears in the schema's type description, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the template_id parameter's provenance workflow (find via list_templates, filter by datasources + type) and clarifies that the resulting report contains the template's pages and widgets. The concrete filtering example adds value beyond the schema descriptions.

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

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

The description states a specific verb (create), resource (report or dashboard), scope (for an existing client), and mechanism (cloning a template's pages + widgets). It distinguishes itself from siblings like create_report (build from scratch) and duplicate_report (copy an existing report rather than a template) by making the template-cloning behavior explicit.

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

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

The description gives a clear prerequisite workflow: find the template first with list_templates, then filter by datasources + type. It includes a concrete example (datasources=gadw, type=DASHBOARD for Google Ads), which tells the agent exactly how to precede this call. It stops short of explicitly naming when to prefer create_report or duplicate_report over this tool, but the workflow guidance is strong.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, and the description is consistent with them. It adds useful behavioral detail beyond the annotations by disclosing that pages, widgets, and datasource categories are automatically copied or derived from the source report.

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 no filler. The core purpose is front-loaded, and the second sentence provides high-value behavioral detail about what gets copied without repeating schema content.

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

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

For a 3-parameter tool with full schema coverage and an output schema, the description is sufficiently complete: it states what the tool does, what it copies, and the source input. The main gap is the lack of explicit guidance on choosing this tool over related create/duplicate tools, but that is already covered under usage guidelines.

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 thoroughly. The description reinforces the role of report_id by mentioning copied pages/widgets, and adds 'datasource categories' as an extra effect, but it does not materially improve an agent's understanding of how to supply the parameters.

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

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

The description states a clear action ('Create a template') with a specific source resource ('from an existing report'), and further specifies what is copied or derived. This makes it distinct from sibling tools like create_report_from_template and duplicate_report, even without reading those definitions.

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 context is implied: use this when you have an existing report and want to create a template from it. However, the description does not explicitly say when to prefer this over alternatives such as create_report_from_template, create_report, or duplicate_report, nor does it state any exclusions.

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

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

Annotations already signal a write operation (readOnlyHint=false) that is not destructive. The description adds genuinely useful behavior beyond that: tokens are the 'single source of truth for every visual property,' overlays come from defaults, and setting is_default=true clears any existing default 'atomically.' This side-effect disclosure is exactly the kind of context annotations cannot provide.

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

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

Three sentences, roughly 75 words, with the core purpose front-loaded. Each sentence earns its place: the tokens requirement, the cover/thank-you page behavior, and the is_default side effect. No filler, no repetition of schema content.

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

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

For a tool with 5 parameters and two nested objects, the description plus the rich 100%-covered schema and existing output schema provide enough for correct invocation. The description covers the key behavioral nuances (complete tokens, default clearing, overlay defaults). A minor gap is that it doesn't explicitly note cover_page/thank_you_page are optional, though the schema's required list already conveys that.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the completeness requirement for tokens and adds the atomic default-clearing nuance for is_default, but the schema already documents each parameter thoroughly (including the full token list and the 'one per account' default semantics). The added value over the schema is marginal.

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 'Create a new visual theme' states a specific verb and resource, and the rest of the description clarifies what a theme is (tokens map, cover/thank-you page images, default flag). This clearly distinguishes it from siblings like update_theme, get_theme, list_themes, and archive_theme, which are all different operations on the same resource.

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 — create a new theme when you need a fresh visual theme and supply the complete tokens map. However, it never explicitly names alternatives or exclusions, such as 'use update_theme to modify an existing theme' or 'use get_theme to inspect current settings.' Given the large sibling list, explicit routing would meaningfully help an agent.

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, destructiveHint=false and openWorldHint=true, so the safety and reach profile is covered. The description adds that these are enumerable, selectable values scoped by params, which is useful but modest; it says nothing about rate limits, paging, or result size for large value sets.

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 tightly written sentences: the first defines the resource, the second routes the agent relative to describe_datasource. No filler, and the purpose is front-loaded.

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

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

For a read-only listing tool with a full output schema and complete schema parameter descriptions, nothing essential is missing. The description supplies the conceptual framing (selectable values for advanced keys) that the structured fields cannot convey.

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 datasource_id, client_id, resource, and the params object (including that params keys are named by describe_datasource). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the selectable values behind a widget's advanced settings and filters') and enumerates concrete examples (campaigns, ad sets, forms, videos, alerts). It also positions itself against the sibling describe_datasource, so an agent can distinguish the two without opening either schema.

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

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

Explicitly frames the relationship: describe_datasource says WHICH advanced keys a data view requires, while this tool returns the values to put in them. That is a clear when-to-use signal via the alternative tool, though it does not spell out exclusions or prerequisites beyond the required datasource_id/client_id/resource.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: it lists the full catalog of supported datasources rather than account connections, and clarifies the id format used elsewhere. No contradictions, but no additional rate-limit or response-size caveats are needed for this simple zero-param call.

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

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

Three sentences, each earning its place: the first states the core action and output fields, the second gives the typical call order, and the third disambiguates from a sibling. No filler or redundancy.

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

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

For a zero-parameter, read-only list tool with an output schema and strong annotations, the description covers what the tool returns, how to use it in the workflow, and when to choose a different tool. 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?

The tool has zero parameters, so the baseline is 4. The description adds meaning about the datasource_id field and its role elsewhere, which is useful context for selecting and processing results, even though no parameter documentation is 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?

The description names a specific verb ('List every datasource Oviond supports') and resource, and enumerates the returned fields (id, name, category, data views). It clearly distinguishes itself from siblings like describe_datasource and connected_datasources.

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 instructs the agent to call this FIRST to obtain the datasource_id, then use describe_datasource, and directs to connected_datasources for account-specific connections. This is concrete, actionable routing guidance.

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

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

Annotations already include destructiveHint=true, but the description adds concrete impact information: 'every widget pulling data from it will break'. This goes beyond the generic destructive flag by telling the agent exactly what downstream effect to expect.

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

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

A single, well-structured sentence conveys the action and its most important consequence without wasted words. The key behavioral warning is front-loaded.

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

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

For a one-parameter destructive tool with annotations and an output schema, the description covers everything needed: what to delete, where to get the ID, and what impact to expect. Nothing critical is missing.

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

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

Schema description coverage is 100%, and the only parameter connection_id already includes a useful origin hint ('from connected_datasources'). The description does not need to add more parameter detail; baseline 3 is appropriate.

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

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

The description states the specific action ('delete a datasource connection') and the resource affected, and immediately clarifies the consequence. This clearly distinguishes it from related operations like unlink_datasource or rename_connection.

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 use when one wants to permanently remove a datasource connection and accept that dependent widgets will break. It does not explicitly contrast with sibling tools like unlink_datasource, leaving the choice 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?

The annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds no behavioral context beyond stating the deletion. It does not disclose whether contained folders are also deleted, whether permissions are required, or whether the action can be undone.

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 filler or repetition. Every word directly contributes to stating the tool's function.

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 delete operation with destructiveHint=true and an output schema present, the description is largely sufficient for invocation. The main gap is the lack of detail about impacts on folder contents, but annotations and schema compensate for the core safety and parameter concerns.

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

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

The single parameter is fully documented in the schema with a helpful 'from list_folders' hint, so the description does not need to add parameter meaning. Baseline 3 applies because schema coverage is 100% and the description adds nothing further.

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 action ('Delete') on a particular resource ('client folder'), making the tool's purpose immediately understandable. It is distinct from sibling tools like create_folder, update_folder, and move_client_to_folder, though the phrasing closely mirrors the title.

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 provided about when to use this tool versus alternatives, such as archiving instead of permanently deleting. There is no mention of prerequisites, reversibility, or caveats, so the agent is left without decision support.

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 supply destructiveHint=true and readOnlyHint=false. The description adds no behavioral context beyond the raw delete action, such as cascading removal of widgets, permanence, or authorization 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?

One short, front-loaded sentence with no filler. It delivers the core action and object immediately and earns every word.

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-required-parameter destructive operation with safety annotations and an output schema, the minimal description is sufficient for invocation. It could add a note about whether the page's widgets are deleted too, but that is not essential for the agent to call the tool correctly.

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

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

Schema coverage is 100% and the page_id property is already described ('Page ID to delete (from list_pages)'). The description merely echoes 'by ID' and contributes no new parameter semantics, so the high-coverage 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 ('Delete') and resource ('a page by ID'), and the title narrows it to report pages. This is clearly distinct from sibling tools like delete_widget, delete_folder, and delete_connection.

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

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

The intended use is implied by the verb—call it when a page needs to be removed—but there is no explicit when/when-not guidance or comparison to alternatives. With many archive_* and delete_* siblings, a sentence saying 'permanently removes a page; use archive_* to keep it recoverable' would materially improve 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?

The annotations already declare destructiveHint=true, so the destructive nature is captured structurally. The description adds no extra behavioral context such as permanence, cascading effects, permissions, or irreversibility.

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 direct sentence with no filler. It is appropriately sized for a simple one-parameter delete operation.

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 one-parameter delete with an output schema and destructive annotation, the description is nearly sufficient. The main missing element is a note distinguishing it from delete_widgets, but the schema and annotations cover the essential calling information.

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 widget_id parameter is clearly documented as coming from list_widgets. The description's 'by ID' adds no new semantic value beyond the schema, so the baseline score 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 ('Delete a widget by ID'), making the core action clear. It does not explicitly differentiate from the sibling tool delete_widgets, though the singular 'a widget' and 'by ID' imply a single-target operation.

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 provided about when to use this tool versus delete_widgets, archive operations, or other removal paths. The schema mentions obtaining the ID from list_widgets, but the description itself gives no usage context or exclusions.

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