Oviond

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

The description goes beyond annotations by disclosing the cloning behavior with fresh IDs and the stacking of widgets below existing ones. It also surfaces the demo-data fallback for unconnected datasources/goals/metrics, which is a non-obvious side effect. This is significant behavioral context for an operation that will modify a page.

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 focused sentences: the first states the core action, the second covers cloning, placement, and fallback behavior. No filler or redundant repetition of the title/schema. Front-loaded with the main purpose.

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

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

For a mutating bulk-add operation, the description plus full schema descriptions and output schema are sufficient to understand invocation. It lacks explicit notes on idempotency or failure modes, but these are minor given the transparent cloning statement. Overall adequate for an AI agent to select and invoke 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 describes all four parameters and references the list_* sources for valid IDs. The description adds no extra parameter-level meaning, so it relies on the schema. Baseline 3 applies because schema coverage is 100%.

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 and resource: instantiate an asset's widgets onto a report page. It distinguishes itself from single-widget add tools by explaining that all of an asset's widgets are cloned. It does not explicitly name sibling tools like add_report_section or add_*_widget, so differentiation is implicit rather than explicit.

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

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

No guidance is given on when to choose this tool over alternatives such as add_report_section or the individual add_*_widget tools. The intended context is only implied by 'instantiate an asset's widgets.' There are no prereq notes or exclusion statements.

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

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

Annotations already establish that this is a non-read, non-destructive write operation, and the description does not contradict them. It adds one meaningful behavior – position, width, and height are auto-defaulted rather than configurable – but it doesn't disclose the resulting defaults, possible duplication behavior, or any 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 short sentences with no filler; the primary action is front-loaded and the defaults note earns its place by explaining an otherwise missing aspect of the API. It is appropriately sized for the tool's low 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?

With an output schema, complete parameter descriptions, and annotations, the description covers what an agent needs to select and call the tool. The only minor gap is the vagueness of 'sensible defaults' – an agent cannot predict or communicate the exact resulting position and size – but this is not critical for invoking the tool.

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

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

Schema description coverage is 100%, so the schema already defines each parameter. The description's only contribution is the 'sensible defaults' note, which explains why position, width, and height are absent from the schema but does not add semantics to link, text, page_id, client_id, or source_id.

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 an explicit action ('Add') with a specific resource ('button widget') and target ('a page'). The resource name differentiates it from siblings such as add_text_widget and add_image_widget, and the defaults sentence clarifies scope 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 implies when to use it – when the user wants a button widget placed on a page – but it does not explicitly address alternatives or exclusions. There is no mention of when to prefer another add_*_widget sibling or update_button_widget, so the guidance relies on inference from the tool name.

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

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

Annotations only indicate readOnly=false and destructive=false, so the description carries meaningful behavioral disclosure: the widget initially shows demo data, is a table trended by date, returns a widget_id, and inherits editor layout properties. There is no contradiction with 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 dense sentences, each contributing unique information: creation semantics, return value and next step, and layout inheritance. There is no filler and no mere repetition of the tool title or 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?

Given that an output schema exists and annotations are present, the description fully covers what the tool does, what it returns, what the initial widget state looks like, and how to proceed after creation. The agent can correctly invoke it and understand the expected follow-up actions.

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

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

All three parameters are fully described in the schema at 100% coverage, so the schema is doing the heavy lifting. The description adds workflow context about update_data_widget and list_calculated_metrics, but does not deepen understanding of the three required parameters 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?

The description states a precise verb+resource combination: 'Add a Calculated Metric widget to a page' and characterizes the widget as a date-trended table with demo data until configured with a formula. This clearly identifies what is being created and differentiates it from the many add_*_widget siblings without needing to name them explicitly.

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

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

The description makes the use case explicit and provides a clear follow-up path: return the widget_id, then configure it with update_data_widget using a calculated metric id from list_calculated_metrics. It does not explicitly list when-not-to-use or compare against add_data_widget/add_custom_data_widget, so it stops 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 only indicate it is not read-only and not destructiveasi no contradiction. The description adds meaningful behavioral detail: the widget initially shows demo data, returns a new widget_id, and has position/size behavior matching the editor's Custom Data card. This goes beyond what the annotations reveal.

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 concise and front-loaded: it states the action, the initial state, the return value, and the follow-up configuration steps in a tight, logical flow. Each sentence contributes necessary information without 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 tool with only three required parameters and an output schema, the description covers the key context an agent needs: what the widget does initially, what the return value is, how to configure it next, and where to get the required IDs and column names. No crucial information 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 has 100% description coverage for all three required parameters, each sourced from list_pages, list_clients, or list_reports. The tool description does not add extra 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 verb and resource: 'Add a Custom Data widget to a page', and describes its behavior as 'a table showing demo data until it points at an uploaded CSV dataset.' This clearly distinguishes it from related sibling tools like add_data_widget or add_button_widget, which serve different widget 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 gives clear workflow context by explaining that the returned widget_id should be used with update_data_widget, and where to get advanced.custom_data_id and column names. It does not explicitly list exclusions or alternatives, but the focused purpose and follow-up configuration make the intended usage 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?

The description adds meaningful behavioral context beyond the annotations: it states that the series is fetched in the background and requires a follow-up call to get_widget_data, that omitting config yields a default widget with demo data, and that position/size default. These are not disclosed by the annotations (readOnlyHint false, destructiveHint false) and significantly help an agent set expectations.

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 about 80 words, starts with the core purpose, and each sentence adds a distinct piece of information: rules, id discovery, return value, background fetch, default behavior, and positioning default. It is front-loaded and avoids repeating schema details, making it efficient for an agent to parse.

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 tool's complexity (17 parameters, nested objects, 100% schema coverage, and an output schema), the description covers the essential workflow and the most critical edge case (default demo widget). It does not enumerate all parameters, but the schema handles that. It could have mentioned the required client_id/page_id sources, but the schema already includes those descriptions, so the description 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?

With 100% schema description coverage, the baseline is 3, but the description adds cross-cutting parameter context: 'applying the same rules as the report builder' explains how datasource defaults affect sort/row limit, and 'Discover ids with datasources → describe_datasource' tells agents where to obtain values for source_id, metrics, dimensions, and advanced settings. This adds meaning beyond individual parameter descriptions.

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

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

The description clearly states the action: 'Add a DATA widget to a page and configure it.' It distinguishes this tool from its siblings by explicitly naming the widget type (DATA) and describing configuration and the returned widget_id. The scope is precise and leaves no ambiguity about what the tool accomplishes.

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 a clear workflow: discover ids with datasources → describe_datasource, then add the widget, then call get_widget_data to read the numbers. It also gives an alternative use case (omitting config for a default demo widget). However, it does not explicitly contrast with other add_*_widget tools, so it lacks explicit 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 signal a write operation (readOnlyHint=false). The description adds useful context — the backend detects the DNS provider and returns records for the user to configure — but omits caveats like reversibility, duplicate-handling, or preconditions. The added value is modest but real.

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 compact sentences with no filler. The core purpose is front-loaded and the behavioral detail follows 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 one-parameter tool with an output schema present, the description adequately conveys what happens and what the user receives. A minor gap is the lack of connection to email-domain or verification tools, but this doesn't block 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% with a clear type, description, and example ("reports.example.com"). The tool description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

"Add a custom domain" is a specific verb+resource statement. The qualifier "custom" and the follow-up about returning DNS records clearly differentiate it from the sibling add_email_domain, which targets a different 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 its use case (adding a custom domain and getting DNS configuration) but gives no explicit when-to-use guidance or alternatives. It does not distinguish itself from add_email_domain or reference related steps like verify_email_domain, leaving selection partly to inference.

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

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

Annotations only indicate that the tool is not read-only and not destructive. The description adds one useful behavioral fact: the tool returns DNS records for configuration, implying it does not perform the DNS setup itself. It does not address idempotency, authentication, or duplicate-domain behavior, but for a simple creation tool this is acceptable.

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 sentence that front-loads the verb and resource and places the side effect in a parenthetical. Every word earns its place with no redundancy.

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

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

Given a single required parameter, an output schema, and annotations covering the basic safety profile, the description supplies the essential action and its key outcome. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

The only parameter is fully covered by the schema, which provides a type and example ('mail.acme.com'). The description adds no additional parameter semantics beyond labeling it a sending domain, so the baseline 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 specific verb and resource: 'Add a sending domain' and tells the agent the key outcome, that DNS records are returned. The qualifier 'sending' differentiates it from the sibling add_domain, while the DNS-record detail separates it from create_email_sender or verify_email_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 phrase 'sending domain' and the DNS-record side effect imply the tool is for initiating email-domain setup, but the description gives no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like verify_email_domain or how to proceed after DNS records are configured.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so it's a mutating but not destructive operation. The description adds one behavioral detail: position, width, and height use sensible defaults, which clarifies that these are optional and will be auto-set. However, it doesn't mention side effects, required permissions, or what happens on failure. This is minimal but not contradictory.

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 that front-loads the purpose and adds a useful note about defaults. Zero wasted words, well-structured for quick parsing.

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-operation with 5 parameters and an output schema, the description is minimal. It covers the core action and the defaults behavior, but lacks usage guidance and behavioral nuance. The schema and output schema handle parameter details and return values, so this is adequate but not rich. Given the tool's relative simplicity, a 3 is appropriate.

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 nothing about parameter meaning or relationships; it only mentions defaults for properties not in the schema. This meets the baseline but doesn't enhance understanding 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 'Add an embed widget to a page', a specific verb and resource. It distinguishes the tool from other add_*_widget siblings by naming the widget type, though it doesn't explicitly contrast with them. The defaults comment adds context but doesn't affect purpose clarity.

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

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

No guidance on when to use this tool vs alternatives like add_button_widget or add_image_widget. It doesn't mention prerequisites (e.g., that page_id and client_id must come from list_pages/list_clients, though schema hints at this) or when this tool would be inappropriate. The description provides no explicit usage conditions or exclusions.

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

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

The description discloses key behaviors beyond the annotations: the widget initially displays a demo target, returns a widget_id for later configuration, inherits goal-defined metric/query/target/comparison settings, and matches the editor's Goal card dimensions. It does not mention permissions or reversal, but the annotations already indicate a non-read-only, non-destructive operation and the description adds meaningful 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?

Three sentences deliver the core action, return value, configuration path, and the widget's distinguishing behavior with no redundancy. The most important operational details are 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 widget-creation tool with full schema coverage and an output schema, the description covers the full lifecycle: what the widget is, what it returns, how to configure it, why it needs no metrics/dimensions, and how its layout behaves. Nothing essential is missing.

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

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

Schema description coverage is 100%, so each parameter (page_id, client_id, source_id) is already documented with source references. The description adds workflow context but no additional parameter-specific semantics, 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 tool's action and resource: adding a Goal widget to a page, specifically a progress gauge that shows a demo target until linked to a saved goal. It also distinguishes it from sibling add_*_widget tools by referencing the goal's self-contained metric query, target, and comparison.

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 actionable guidance: after adding, configure the widget via update_data_widget with advanced.goal_id from list_goals, and notes that no metrics or dimensions need to be passed. It does not explicitly contrast with alternatives like add_data_widget or add_calculated_metric_widget, but the use case is specific and clear enough.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description only needs to add context beyond the safety profile. It contributes the "sensible defaults" note, which usefully preempts the agent from hunting for position/width/height parameters that don't exist in the schema. It doesn't disclose side effects like whether the widget is appended or replaces content, but with annotations present the bar is lower and the description clears it minimally.

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 action front-loaded and the second sentence earning its place by clarifying default layout behavior. There is no fluff and no repetition of schema content, though it is terse enough to be borderline under-specified.

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 structured data carries most of the weight here: 100% parameter coverage, annotations for the mutation profile, and an output schema for return values. The description covers purpose and defaults adequately, but leaves the agent without any cross-tool selection context — the same gap flagged under usage_guidelines — so it is adequate rather than complete.

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

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

Schema description coverage is 100%, so each of the six parameters is already documented — including the link vs link_url distinction and the image_fit default. Per the rubric this sets a baseline of 3; the description's "sensible defaults" hint adds a small amount of signal but no per-parameter meaning beyond the schema.

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

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

"Add an image widget to a page" names a specific verb, resource, and destination, and the resource type distinguishes it from sibling widget tools like add_text_widget and add_button_widget. It doesn't explicitly contrast with siblings, but the object "image widget" carries the differentiation and the defaults note adds useful scope.

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

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

The description gives no guidance on when to choose this tool over alternatives — no mention of when add_asset_to_page or another widget adder would be more appropriate, and no when-not conditions. Among 15+ add_*_widget siblings, an agent receives no routing help beyond 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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation is expected. The description adds valuable behavioral context: it explains automatic page handling (single-page auto-use, multi-page returns pages) and clarifies that the tool works for both reports and dashboards. This goes beyond what annotations provide, though it doesn't detail side effects like whether adding a section modifies the report irreversibly.

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 scope, the second gives the prerequisite lookup, the third explains the page-handling nuance. Information is front-loaded and no filler exists.

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 key operational details: what to find first, how page_id behaves, and that it applies to both reports and dashboards. With an output schema present and annotations covering safety, the description is nearly complete. It could mention what happens if the asset is already on the page or whether the section is added at a specific position, but these are minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds extra meaning by explaining the page_id behavior (omit for single-page, or to list pages when multiple) and by clarifying that asset_id refers to a saved section from list_assets. This supplements the schema rather than merely repeating it.

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

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

The description states a specific verb ('Add'), a specific resource ('a saved section (asset) to a report'), and explicitly notes it works for both reports and dashboards. It also distinguishes itself from sibling tools by naming list_assets as the prerequisite finder, which helps an agent understand what this tool does versus other 'add_*' 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 when-to-use guidance: find the section first with list_assets, and explains page handling behavior (single-page vs multi-page) so the agent knows when to pass page_id. It also implicitly differentiates from sibling add_*_widget tools by focusing on saved sections/assets rather than 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds valuable behavioral context beyond annotations: the widget has no datasource, never fetches, content is inline, and omitting the value defaults to 0. It also notes that position/width/height match the editor's card, which is useful placement context. Minor gap: it doesn't state whether adding is idempotent or what the response contains, but the output schema likely covers return values.

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

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

Three sentences with no filler. The core purpose is front-loaded, the distinguishing behavior (no datasource, inline content) comes second, and the practical default/alternative guidance is last. 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 create-style tool with 5 params, 100% schema coverage, and an output schema, the description is nearly complete. It explains the widget's unique behavior, the default value, and the update path. It doesn't explicitly state prerequisites (e.g., that the page must exist) or whether the widget is immediately visible, but those are minor given the schema and output schema context.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds meaning for 'value' (typed-in content, examples like 'R50' or 'Active', defaults to 0) and clarifies that source_id is the report ID, but it doesn't add much beyond the schema for name, page_id, or client_id. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb ('Add') and resource ('Static Value widget to a page'), and clearly distinguishes it from sibling card tools by explaining it has no datasource and never fetches. It also names the sibling update_static_value_widget for later edits, so an agent can tell this tool apart from add_data_widget, add_goal_widget, etc.

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

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

The description explicitly says when to use this tool (to add a static KPI card with inline content) and contrasts it with 'the other cards' that have datasources. It also gives a clear alternative: omit the value to land on 0 and set it later with update_static_value_widget. This is explicit 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 indicate this is a non-read-only, non-destructive operation. The description adds one behavioral detail: the tool automatically applies default values for position, width, and height. However, it leaves 'sensible defaults' undefined and does not disclose any side effects or prerequisites.

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

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

The description is a single sentence with a front-loaded action clause and a short clarifying detail. It is concise, contains no redundant wording, and every word contributes value beyond what the schema and annotations already provide.

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 creation tool with a complete output schema and full parameter documentation, the one-sentence description is largely sufficient. The only real gap is that 'sensible defaults' is vague, but the agent can still invoke the tool correctly based on the provided schema and the description's core purpose.

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

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

Schema description coverage is 100%, so each parameter is already documented (e.g., page_id from list_pages, client_id from list_clients). The description contributes by explaining that position, width, and height parameters are not needed because defaults are applied, but it does not add meaning to the existing schema properties beyond that.

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 ('Add') and resource ('rich-text widget') along with a placement target ('to a page'). This clearly distinguishes it from sibling tools like add_button_widget or add_image_widget, since 'rich-text' names the widget subtype and the description is not a tautology.

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 does not mention any alternative tools or explicitly state when to use this versus other add_*_widget siblings. It gives a contextual hint that position, width, and height use sensible defaults, which implies the tool is meant for quick adds without custom layout needs, but it is not an explicit routing guideline.

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

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

Annotations only declare readOnlyHint=false, so the description must convey write behavior and side effects. It states that position, width, and height use sensible defaults, which is useful, but it does not mention permissions, reversibility, or what happens to existing widgets. It does not contradict 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 two short sentences with no redundancy. The core action is front-loaded, and the additional note about defaults is directly relevant to expected behavior. 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 tool has an output schema, and the input parameters are well-documented, so basic calling is clear. However, the description does not explain how a title widget differs from other widget types or when to prefer it, and the defaults statement is vague about placement. For a simple add operation it is minimally complete but not rich.

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

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

Schema coverage is 100%, so all five parameters are already described with their own meanings and defaults. The description adds no extra parameter-level detail, and its mention of position/width/height refers to non-existent parameters, which is slightly ambiguous. Baseline 3 applies because the schema carries the burden.

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

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

The description uses a specific verb ('Add') and resource ('title widget') and clarifies the target ('to a page'). It distinguishes from siblings like add_text_widget or add_button_widget by naming the widget type explicitly, and the mention of defaults adds operational scope.

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

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

The description offers no guidance on when to use this tool versus alternatives like add_text_widget or add_heading_widget. It does not state when not to use it, nor does it reference sibling tools or provide selection criteria. Usage is only implied by the name.

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

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

Annotations already declare destructiveHint=true, but the description adds meaningful behavioral nuance: archiving affects widget rows and is recoverable via restore_from_archive. This clearly explains the 'soft delete' nature and what the operation does beyond the raw destructive hint. 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?

Two compact sentences with zero filler. The core action and target are front-loaded, and the recovery mechanism is stated efficiently. 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 tool with an output schema and annotations, the description covers the essential context: what gets archived, that it is recoverable, and where to find it afterward. No critical information for invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, and the description does not add parameter-specific meaning beyond what the schema provides ('Asset ID to archive (from list_assets)'). The baseline of 3 is appropriate; the schema carries the parameter documentation burden.

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

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

The description uses a specific verb 'archive' and clearly identifies the resource: 'a saved section and its widget rows.' It also clarifies the semantic distinction from deletion with 'not away,' which helps differentiate from delete_* siblings. This is unambiguous about what the tool does.

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

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

The description provides lifecycle context by mentioning list_archive and restore_from_archive, implying this tool is for reversible archiving. However, it does not explicitly state when to choose this over related tools like delete_* or when not to use it, leaving the usage decision partially inferred.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not the only source of behavioral context. It adds valuable detail beyond that: archiving is reversible, the automation appears in list_archive, and restoring it reschedules deliveries. No contradiction with 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 compact sentences, front-loaded with the action and consequence. The phrase 'not away' earns its place by preventing a deletion misread, and naming list_archive/restore_from_archive provides concrete navigation in the same breath.

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

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

For a two-parameter operation with an output schema and destructive annotations, the description covers the essential lifecycle: what archiving does, where it goes, and how to reverse it. The only meaningful gap is the unaddressed distinction from pause_automation, which was already scored 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%, and both required parameters (id, parent_id) already have descriptive schema entries referencing list_automations, list_reports, and list_clients. The tool description adds no parameter-level semantics, so the schema baseline of 3 applies.

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

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

The description opens with a specific verb-resource pair, 'Archive an automation,' and immediately states the key effect: stopping scheduled deliveries. It then distinguishes archiving from deletion by naming the archive lifecycle ('list_archive shows it' and 'restore_from_archive brings it back'), which separates it from sibling operations like archive_asset or delete actions.

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 conveys when to use the tool: when an automation should stop delivering but be retained and restorable. However, it never compares it to the sibling pause_automation, which likely also stops scheduled deliveries, so the guidance is implied rather than explicit.

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 mark destructiveHint=true, but the description adds meaningful behavioral nuance by stating the item goes to the archive and can be listed/restored, making it clear the action is not permanent deletion. It also references sibling tools that are part of the archive lifecycle. This goes beyond the annotations and helps the agent predict the tool'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?

The description is two short sentences with the key information front-loaded. Every word is functional: it states the operation, the target, the ID requirement, and the reversible nature. No fluff.

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

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

For a tool with only one input parameter, an output schema, and annotations already covering mutability, the description is complete. It covers what happens (archived), how to undo it, and how to view archived items, leaving no important gaps for an agent to call it safely.

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 covers the single parameter 'id' with a description and provenance ('from list_calculated_metrics'), so the description adds no additional parameter semantics. Per baseline for high schema coverage, this is 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 states a specific verb ('Archive'), a specific resource ('calculated metric'), and the mechanism ('by ID'), making its purpose unambiguous. It also distinguishes the operation from permanent deletion by noting it's not destroyed, which is useful context. This clearly separates it from sibling archive_* tools that target different resource 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 gives clear context that archiving is reversible and points to list_archive and restore_from_archive as related operations, but it does not explicitly explain when to prefer this over other archive_* tools or when not to use it. The guidance is implied rather than explicit, so it earns a 4 rather than 5.

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

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

Despite destructiveHint=true, the description usefully discloses the cascade to reports, exports and automations, and clarifies the client is not permanently deleted because list_archive and restore_from_archive exist. This adds real behavioral 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?

Two compact sentences front-load the action and scope, then add the key recovery caveat. No filler or redundant 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 single-parameter tool with an output schema and adequate annotations, the description covers the operation's scope, side effects and reversibility, which is all an agent needs 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% and the id parameter already says 'Client ID to archive (from list_clients)'. The description adds only the 'by ID' framing, so it does not provide extra parameter semantics beyond the schema.

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

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

States a specific verb ('Archive'), resource ('client'), key parameter ('by ID'), and scope ('with its reports, exports and automations'). This differentiates it from sibling archive_report/archive_export/archive_automation and from archive_clients by indicating a single-client, cascading 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 selection context: use for archiving a single client and its dependent objects, and clarifies the operation is recoverable via list_archive/restore_from_archive. It does not explicitly contrast with archive_clients or say when not to use it, so it falls just short of full when/when-not guidance.

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

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

The description adds meaningful behavioral context beyond the annotations: archiving is recoverable ('not away'), and it names the exact tools to view and reverse the operation. DestructiveHint=true is not contradicted since this is still a non-read-only state change, but the recoverability nuance is valuable.

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 states the action and scope, the second clarifies lifecycle behavior. The most important information is front-loaded, and 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?

For a single-parameter, batch archive operation, the description plus annotations and output schema cover everything an agent needs to invoke it correctly. It explains what happens to the clients and how to recover them, leaving no critical 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% for the single parameter, and the schema already says 'Array of client IDs to archive (from list_clients)'. The description reinforces the 'by ID' and 'in one call' aspects but adds no new parameter-level semantics beyond what the schema provides.

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

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

The description states a specific action ('Archive several clients by ID in one call') and clearly identifies the batch scope, distinguishing it from the singular archive_client sibling. It also names related lifecycle tools (list_archive, restore_from_archive), reinforcing what the tool is for.

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: use this when archiving multiple clients in a single call, and it points to list_archive/restore_from_archive for later retrieval. It doesn't explicitly exclude the singular archive_client alternative, but the batch framing makes the intended usage evident.

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, but the description adds crucial context beyond that: it clarifies the action is reversible ('goes to the archive, not away') and explicitly names the tools that reverse or display it. This extra behavioral disclosure is valuable and does not contradict the destructive hint.

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, front-loaded sentences with zero redundancy. The action is stated first, and the clarifying clause about reversibility is concise and directly 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 simple, single-parameter archive operation, the description fully addresses what the agent needs: it explains the permanent-vs-archived nature, points to related tools for listing and restoring, and is sufficient given the low complexity and available annotations and output schema.

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

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

The single parameter 'id' is fully described in the schema (from list_custom_data). The description adds no additional meaning beyond what the schema provides, so the baseline of 3 is appropriate 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 states a specific verb ('Archive'), a clear resource ('custom-data dataset by ID'), and distinguishes the action from deletion with 'not away'. It clearly differentiates from sibling archive_* tools by focusing on custom data, 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 context by mentioning list_archive and restore_from_archive as complementary tools, signaling that this is the reversible archiving step. However, it does not explicitly state when to use this over other tools (e.g., delete_custom_data is not listed), but the 'not away' phrasing gives a clear hint that it is non-destructive in the long term.

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 include destructiveHint: true and readOnlyHint: false, so the description's clarification that the record 'goes to the archive, not away' and can be restored adds valuable context beyond the annotations. It discloses that the operation is reversible and not a permanent deletion, which is critical behavioral information an agent needs. No contradiction with the annotations, as 'destructive' here means a state-changing move, not irreversible destruction.

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 structure. The first sentence states the action and target, the second clarifies the effect and provides the related tools. Every word earns its place, with no fluff or repetition. It is front-loaded with the core purpose and uses the em-dash effectively to add crucial nuance.

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 single parameter, an output schema present, and annotations covering safety, the description is quite complete. It covers the purpose, the reversible nature, and the related tools (list_archive, restore_from_archive). It does not mention error conditions or prerequisites, but the schema's reference to list_exports implies the ID source. Overall, an agent has enough information to invoke it correctly without ambiguity.

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

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

The input schema already fully describes the single parameter 'id' with the note 'Export ID (from list_exports)', giving 100% coverage. The description adds only the redundant phrase 'by ID' and does not provide any additional semantic details such as format, validity, or constraints. Since the schema carries the full burden, the description's contribution is minimal, warranting the baseline score of 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 states a specific verb ('Archive'), a resource ('a PDF export record'), and the method ('by ID'). It also clarifies the action is not permanent deletion ('not away'), which distinguishes it from destructive delete operations and aligns with the archive_* family of siblings. The mention of list_archive and restore_from_archive further disambiguates its role in the lifecycle.

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 lifecycle context by naming list_archive and restore_from_archive, implicitly telling the agent that archiving is reversible and that these tools are the complementary operations. However, it does not explicitly state when to use this tool versus alternatives like delete or other archive tools, though the name and specificity to PDF exports largely remove ambiguity. The 'not away' phrasing also implies it should not be used when permanent deletion is intended.

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 destructiveHint=true, but the description adds crucial context: the goal is not permanently deleted and can be viewed and restored via list_archive and restore_from_archive. This clarifies the reversibility and reduces the perceived destructiveness, going beyond the raw 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?

The description is two sentences with zero redundancy. The primary action and ID reference are front-loaded, and the clarifying clause about reversibility is efficiently placed. 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 existing output schema, the description covers all essential behavior: what happens to the goal, how to retrieve it later, and how to undo. No additional context is needed for correct invocation.

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

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

The schema already provides a full description for the single parameter (id: 'Goal ID (from list_goals)') with 100% coverage. The description adds no additional semantic meaning about the parameter, so the baseline of 3 applies.

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

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

The description clearly states the action (archive), the resource (goal), and the method (by ID). It also distinguishes the tool from other archive_* siblings by naming the specific resource type. The phrase 'It goes to the archive, not away' clarifies the semantic intent, making it 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 when to use this tool (soft-delete a goal) and mentions related tools (list_archive, restore_from_archive) that explain the lifecycle. However, it does not explicitly compare against alternatives like deleting a goal (which isn't in siblings) or other archive tools, leaving some inference to the 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 indicate destructiveHint=true, but the description clarifies that the action is actually non-destructive (reversible) and only becomes permanent upon explicit deletion from the archive. This adds valuable context beyond the annotation and prevents the agent from overestimating the tool's destructive impact. It also explains the storage behavior.

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

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

The description is two sentences, front-loaded with the primary action, and every phrase adds value: it states the action, corrects a likely misconception, names the recovery tools, and specifies the only deletion condition. No redundant 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 simple tool with one parameter, the description fully covers the behavior: what happens on archive, how to see it, how to restore it, and when it is actually removed. It also references the source of the id (list_media) via the schema. With an output schema present, 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 only parameter 'id' is fully described in the schema ('Media file ID to archive (from list_media)'), so schema coverage is 100%. The description adds no additional information about the parameter beyond what the schema provides, 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 clearly states the tool's action ('Archive a media file') and immediately clarifies that archiving is not deletion ('not away'). It also names the complementary tools (list_archive, restore_from_archive) and the only condition for permanent removal, making the purpose unambiguous and distinguishing it from deletion-related 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 explains the outcome of archiving (goes to archive, can be listed/restored) and clarifies that it is not permanent deletion, which guides an agent on when to use it. However, it does not explicitly address alternative archive tools like archive_media_files (plural) or archive_asset, so it leaves some differentiation 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 description adds valuable behavioral context beyond the destructiveHint and readOnlyHint annotations: it clarifies that archiving is not permanent ('not away') and that archived media can be listed and restored. It does not cover partial failures or metadata retention, but for a reversible archive operation this is sufficient.

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

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

The description is two sentences with no wasted words. The first sentence states the action and scope; the second sentence disambiguates the permanence of the operation and names the recovery tools.

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 single well-documented parameter, the output schema, and the annotations, the description is complete. It explains what happens to the files, where they appear, and how to reverse the operation, so an agent has enough context to call this tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents ids as 'Media file IDs to archive (from list_media)' with minItems: 1. The description adds only that the operation is batched by ID, which matches the schema without providing additional parameter-level meaning.

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

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

The description states a specific verb and resource: 'Archive several media files by ID in one call.' It clearly distinguishes this batch tool from the singular sibling archive_media_file and from other archive_* tools that target different resource 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 establishes the main use case — archiving multiple files in a single batch call — and explains the recovery path via list_archive and restore_from_archive. It does not explicitly name an alternative for permanent deletion, but the context is clear enough given the tool's reversible behavior.

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 useful nuance by stating the notification is not erased and simply leaves the inbox. This clarifies that archiving is a reversible, non-destructive action despite the destructive hint.

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 and the key behavioral nuance. No filler or redundant detail, and the main action 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 full schema coverage, an output schema, and annotations covering the destructive behavior, the description 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 only parameter id is already described as 'Notification ID (from list_notifications)'. The description adds no additional semantic meaning 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?

Description states an explicit verb and resource ('Archive a single notification by ID') and clarifies non-permanence ('leaves the inbox but is not erased'). It clearly distinguishes from the plural sibling archive_notifications.

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

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

Usage is implied through 'single notification by ID' and the distinction of being archived rather than erased. However, it does not explicitly name the plural alternative archive_notifications or state when to prefer one over the other.

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?

Despite the destructiveHint=true annotation, the description adds valuable context by stating 'They leave the inbox but are not erased', clarifying that the operation is not permanent deletion. This goes beyond the annotation's simple destructiveness flag and gives the agent a clearer model of the tool's 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?

The description is two sentences with no filler. The core action is front-loaded ('Archive several notifications by ID in one call') and the clarifying behavior is added without 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?

For a simple one-parameter batch operation with an output schema present and annotations covering safety, the description is nearly complete. It explains the batch nature, the input method, and the non-destructive outcome. Minor gaps like partial failures or id validation are not addressed, but they are not essential given the tool's simplicity.

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 provides 100% coverage with a description for the 'ids' parameter ('Notification IDs to archive (from list_notifications)'). The description adds 'by ID' but no new constraints, formatting, or behavioral detail beyond the schema. Baseline 3 is appropriate since the schema carries the semantic burden.

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

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

The description clearly states the action (archive), resource (notifications), and method (by ID in one call). It also clarifies that the notifications leave the inbox but are not erased, which distinguishes it from deletion tools. However, it does not explicitly differentiate from the singular sibling archive_notification, though 'several' and 'in one call' imply batch usage.

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 use ('several notifications by ID in one call') but does not explicitly state when to choose this over alternatives like archive_notification (singular) or clear_read_notifications. No exclusions or 'when not to use' guidance is provided, leaving the selection decision somewhat 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?

Beyond the destructiveHint=true annotation, the description clarifies that pages and widgets remain attached and that the report is recoverable ('not away'). This directly addresses what the destructive hint suggests and gives the agent nuanced safety information.

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 brief sentences front-load the action and add only high-value behavior details. No filler or redundant restatement of the schema.

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

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

Given the single parameter, existing output schema, and annotations, the description covers the critical invocation context: what persists, where it goes, and how it can be reversed. Nothing needed for correct use 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 single 'id' parameter, including its origin from list_reports. The description only says 'by ID' and adds no new parameter meaning, so a baseline 3 with full schema coverage 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 the action (archive) and resource (a report by ID), and the title extends it to dashboards. However, it does not distinguish this singular tool from the sibling 'archive_reports' beyond number, so it misses full sibling differentiation.

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

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

It gives useful lifecycle context: archived items appear in list_archive and can be restored via restore_from_archive. It implies when to use the tool (preserve rather than permanently remove), but it doesn't explicitly state when not to use it or how it compares with sibling archive operations.

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

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

Annotations already indicate destructiveHint=true, and the description adds valuable nuance by clarifying that archiving is reversible and not permanent ('not away', 'restore_from_archive brings them back'). This goes beyond the annotation to disclose the non-destructive nature in practice, which is critical for an agent to assess risk.

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: the first states the core action, the second clarifies the outcome and points to related tools. No redundant words, front-loaded purpose, and efficient structure.

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

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

For a simple single-parameter tool with an output schema and annotations, the description covers purpose, scope, and reversibility. It also references the archive lifecycle via sibling tools. Nothing an agent needs to decide whether to call it or interpret results 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 parameter 'ids' is fully described as an array of report IDs. The tool description adds no additional meaning beyond the schema's own description, which already mentions 'from list_reports'. Baseline 3 is appropriate because the schema handles the semantics and the description does not compensate 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 clearly states the verb (archive), resource (reports), and scope (several by ID in one call). It explicitly differentiates from the sibling archive_report by emphasizing batch operation. The phrase 'They go to the archive, not away' clarifies the semantic outcome, making it 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 multiple reports via 'several' and 'in one call', which contrasts with the singular archive_report sibling. However, it does not explicitly state 'use archive_report for a single report' or provide exclusion conditions. It gives lifecycle context (list_archive, restore_from_archive) but lacks 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 declare destructiveHint=true, which could imply permanent deletion. The description adds crucial context that the template 'goes to the archive, not away' and that list_archive shows it and restore_from_archive brings it back, clarifying the exact reversible nature of the operation. This goes beyond the annotation and prevents a misconception.

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 is front-loaded, and the second sentence efficiently conveys the archive lifecycle and related sibling tools. Every sentence adds 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 single-parameter tool with an output schema, the description fully covers what the tool does, how the operation affects the resource, and how to undo it. Combined with the schema and annotations, an agent has everything needed to invoke it correctly without additional documentation.

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 'id' is already documented as 'Template ID to archive (from list_templates)'. The description merely repeats 'by ID' and does not add additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('archive') and resource ('a template by ID'), and immediately distinguishes it from deletion by explaining the archive lifecycle. This clearly separates archive_template from siblings like delete_email_template 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?

The description gives clear context: it archives a template rather than deleting it, and mentions that list_archive and restore_from_archive are the counterpart operations. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'use when you want to temporarily remove a template') or name exclusions, 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 destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate that. It adds valuable behavioral context: reports using the archived theme fall back to the default, and the theme is recoverable via restore_from_archive. This goes beyond the annotations and clarifies the real-world 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?

Three sentences, each earning its place: the action, the consequence, and the recoverability. The most important information (what it does) is front-loaded, and the contrast with deletion is concise and clear.

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 clear schema and annotations, the description is nearly complete. It explains the action, the side effect on reports, and the recovery path. The only minor gap is that it doesn't explicitly state the return value or whether the operation is idempotent, but the output schema likely covers the return, and the description is sufficient 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% — the single parameter 'id' is already described as 'Theme ID to archive (from list_themes)'. The description adds no new parameter-level detail beyond what the schema provides, so the 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 clearly states the action ('Archive a theme by ID'), the resource (theme), and the effect (reports using it fall back to the default). It also distinguishes archiving from deletion, which is a key semantic distinction from sibling tools like delete_* or update_theme.

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

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

The description implies when to use this tool: when you want to archive a theme rather than permanently delete it. It explicitly contrasts with deletion ('not away') and names the related tools list_archive and restore_from_archive, which helps an agent understand the archive lifecycle. However, it doesn't explicitly state when NOT to use it (e.g., use delete_* for permanent removal) or mention prerequisites like the theme not being in use.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses what the audit covers and what kinds of issues it flags. The explicit 'Read-only' statement reinforces the annotations without contradicting them, adding practical 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, front-loaded sentence that states the verb, resource, and expected output without filler. Every clause contributes meaningful information, making it easy for an agent to parse quickly.

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 one well-documented required parameter, a schema coverage of 100%, an output schema available, and annotations covering safety, the description fills the remaining behavioral gap—what the audit inspects and flags. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%; the schema already documents the id parameter and its provenance ('from list_reports'). The description adds no new parameter semantics 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 uses a specific verb ('Audit') with a clear resource ('report or dashboard') and enumerates the concrete outputs: connected data sources, automation state, and flagged issues. This distinguishes it from related sibling tools like get_report or list_automations, which retrieve data but do not aggregate health signals.

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 conveys the intended use case: check a report/dashboard for likely problems such as missing data sources or paused automations. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to route to this tool over simple getters or listers.

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 description's 'Change' is consistent but not additive. It does add the important scoping context that this affects the authenticated user's own account, yet it does not disclose possible side effects such as email verification requirements or impacts on login sessions.

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. Every word contributes meaning, and it is appropriately concise for a tool with one parameter.

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 simple one-parameter mutation with a complete input schema and an output schema present, so the description is nearly sufficient for correct invocation. It lacks only a bit of side-effect or verification context, which would make it fully complete.

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

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

The input schema has 100% coverage, with email_address fully described by name, type, format, and description. The tool description adds no additional parameter detail, 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 states a specific verb ('Change'), a clear resource ('email address'), and the exact scope ('authenticated user's'). This distinguishes it from update_user and get_current_user, which are the relevant sibling alternatives in the tool list.

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

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

The phrase 'authenticated user's' clearly indicates this tool is for changing the caller's own email address, which implies it should not be used to change another user's email. However, it does not explicitly name an alternative like update_user or state a when-not-to-use condition.

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?

While annotations indicate readOnlyHint=false and destructiveHint=false, the description goes much further: it discloses that every data widget is re-fetched and results are saved, that widgets on their own custom range are preserved, that rolling presets are stored as presets and re-resolved later, and that the re-fetch runs in the background. This is precisely the kind of behavioral context an agent needs to anticipate 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?

Three sentences, each packed with necessary information: the core purpose, the behavior for widgets and rolling presets, and the background execution with a pointer to get_widget_data. No filler or repetition, and the most important detail (what the tool does) is front-loaded.

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

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

Given the complexity of the nested date_range object and the presence of an output schema, the description covers everything needed to call the tool correctly: the effect on widgets, the rolling preset behavior, the background execution, and how to retrieve results. Annotation and schema already handle safety and parameter details, 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 description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining how the date_range object behaves: widgets with custom ranges keep them, and rolling presets are re-resolved on later fetches. This clarifies the overall effect of setting date_range, going beyond field-level 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 the specific verb+resource ('Set the period a report covers'), immediately distinguishing this from sibling tools like get_widget_data by stating the action and its object. It also clarifies the scope: it affects all data widgets on the report unless they have their own custom range, which prevents confusion with other update 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 clearly tells the agent to use get_widget_data with source_id set to the report to read the re-fetched results, which directly addresses the common post-action question. It implies when to use this tool (when changing a report's date range) but does not explicitly contrast it with other update tools like update_report, leaving a slight gap in 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 carry destructiveHint=true and readOnlyHint=false, so destructiveness is disclosed structurally. The description adds one valuable behavioral boundary — only already-read notifications are affected, leaving unread ones intact. It does not clarify whether 'delete' is permanent versus a trash/archive state, which is relevant given archive_notifications exists as a sibling.

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 eight-word sentence that opens with the verb and states the full scope. Every word earns its place; there is no filler or redundant restatement of the title.

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

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

For a zero-parameter destructive bulk operation with an output schema present, the description conveys the action, the affected scope, and the exclusivity of the filter. The only remaining gap is an explicit reversibility statement distinguishing delete from the archive sibling, which would make it fully bulletproof.

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

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

With zero parameters, there is nothing for the schema to document, and the description's phrasing 'all notifications that have already been read' confirms this is an unfiltered bulk operation. The baseline 4 for a zero-parameter tool applies, as no parameter semantics need to be added.

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 pairs a specific verb ('Delete') with a precise resource and scope ('all notifications that have already been read'), which clearly distinguishes it from sibling tools like archive_notifications (archive rather than delete), mark_notifications_read (marks rather than deletes), and count_unread_notifications. No ambiguity remains about what this tool accomplishes.

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 its use case — permanently removing already-read notifications — but never explicitly contrasts it with the nearest alternative, archive_notifications, which preserves history. An agent will likely choose correctly for a cleanup goal, but the description offers no explicit when-to-use vs when-not-to guidance relative to the notification-related 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 already establish this as a read-only, non-destructive operation, so the description doesn't need to restate that. It adds valuable behavioral context beyond the annotations: unconnected datasources cannot provide real widget data and will render demo data instead, which tells the agent why the list matters.

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 uses two sentences with no wasted words. The first sentence front-loads the core action and scope, and the second adds one high-value contextual detail about real data versus demo data, making the definition both compact and informative.

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

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

For a zero-parameter, read-only listing tool with an output schema, the description is complete. It explains what is listed, at what scope, and why the distinction between connected and unconnected datasources matters in practice, so an agent has enough information 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?

The tool has zero parameters, so there is no parameter detail that the description must explain beyond the empty schema. The baseline for zero-parameter tools is appropriate here, and the description appropriately focuses on the meaning of the returned list rather than input syntax.

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

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

The description states a specific verb ('List'), a specific resource ('datasource connections'), and a clear scope ('this account has made'). It also adds a distinguishing behavior: only connected datasources can power widgets with real data, while everything else falls back to demo data, which separates this tool from generic datasource listings.

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

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

The description clearly implies when to use this tool: when an agent needs to verify which datasource connections are available for widgets to pull real data. It gives practical context but does not explicitly name sibling alternatives or state when not to use it, so it stops just short of full routing guidance.

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

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

Annotations already declare read-only and non-destructive behavior, so the description only needs to add beyond that. It adds the account-level scope and aggregate 'total count' nature, but does not address whether archived clients are included or how the count is computed. That is acceptable given the output schema and simple nature 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?

The description is a single declarative sentence with no filler. It front-loads the action, resource, and scope, and every word contributes meaning.

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

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

For a zero-parameter, read-only count operation with an output schema, the one-sentence description is complete enough for an agent to invoke it correctly. Return-value specifics are already covered by the output schema, and the annotations cover safety traits.

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 there is no parameter semantics for the description to add. The baseline for 0-parameter tools is 4, and the description is consistent with this by not implying any configurable inputs.

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

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

The description names a specific verb ('Get'), a specific resource ('clients'), and the scope ('for the account'). The phrase 'total count' clearly distinguishes it from list_clients by signaling an aggregate operation rather than a detailed listing.

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 account-level usage through 'for the account,' but it does not explicitly state when to choose this tool over alternatives like list_clients or count_unread_notifications. There is no exclusionary guidance, only an implicit selection condition.

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 no further behavioral detail beyond the count semantics, but it does not contradict annotations.

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

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

A single, front-loaded sentence with no wasted words. It states exactly what the tool does without unnecessary elaboration.

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 parameterless read-only count tool with an output schema and safety annotations, this description is fully sufficient. Nothing needed to invoke the tool correctly is missing.

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

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

The tool has zero parameters, so the schema is trivially complete. The description need not elaborate on parameter meaning, and the baseline of 4 applies.

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

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

The description uses a specific verb ('Get') and resource ('number of unread notifications'), clearly distinguishing it from list_notifications by indicating it returns a count rather than a list. The scope ('unread') is also 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 provides no guidance on when to use this tool versus alternatives such as list_notifications or clear_read_notifications. No exclusions or preferred contexts are mentioned.

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 readOnlyHint=false and destructiveHint=false in annotations, the description carries the burden and discloses meaningful behavior: widgets are copied, receive fresh ids, and inherit type/datasources from the selection. It does not explicitly say original widgets remain untouched, but 'copied' makes that a reasonable inference.

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

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

Two sentences, front-loaded with the action, followed by a concise behavioral explanation and a pointer to the sibling tool. No filler, tautology, or repeated schema details.

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

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

Given the 100% schema coverage and presence of an output schema, the description is complete enough for an agent to invoke the tool correctly. It explains the core behavior, the relationship to widget_ids, and the intended next step.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description's 'what you picked' maps to widget_ids but adds little beyond the schema's 'current config is copied'.

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 concrete action: saving selected widgets into a reusable section, and specifies the core semantics (copied widgets, fresh ids, derived types/datasources). The reference to add_asset_to_page distinguishes this from adding a section directly to a report.

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 editor analogy and the pointer to add_asset_to_page give clear context for when this tool fits in a workflow. However, it does not explicitly name alternatives or state when not to use it, leaving some routing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutating nature. The description adds the behavioral nuance that a custom template gets saved inline as a new named template, which is useful context. It does not disclose any additional side effects like potential overwrites or permission requirements, but given annotation coverage, it is adequate.

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

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

The description is a single, dense sentence that front-loads the core action ('Create a new automation') and then explains the two modes. It is concise and free of fluff, though the second clause is slightly complex. It earns points for efficiency and clarity.

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

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

Given the tool's complexity (13 params, 10 required, nested object, output schema exists), the description covers the key decision point (existing vs custom template) and references the source tools for IDs. It omits mention of required fields like parent_id or the meaning of date_text, but these are fully covered in the schema. The output schema handles return values. It is sufficient but not exhaustive for such 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 each parameter is already documented. The description reinforces the relationship between template_id and the custom payload, but this is also stated in the schema (template_id description and custom description). It adds no new parameter meaning beyond what the schema provides, so a 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 clearly states 'Create a new automation', identifying the specific verb and resource. It distinguishes this tool from siblings by explaining the two creation modes: using an existing template/sender or providing a custom template inline. This differentiates it from create_email_template and create_email_sender while clarifying its own scope.

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

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

The description gives explicit guidance on the two valid usage paths: referencing existing templates/senders by id from the listed tools, or using the 'custom' literal with a payload. This helps the agent decide which parameters to fill. However, it does not explicitly contrast with update_automation or test_automation, nor state when not to use it, though the 'create' intent 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 already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation that is not destructive. The description adds the concept of a 'custom KPI from a formula over other metrics,' which clarifies the semantic behavior. However, it doesn't disclose details like whether the metric is immediately available, whether it can reference other calculated metrics, or what the response contains. With annotations covering the basic safety profile, 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?

The description is a single, efficient sentence that front-loads the core purpose. It earns its place by defining the resource type and its nature. It could arguably add a pointer to the formula example in the schema, but the current length is appropriate and not padded.

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

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

The tool has a rich output schema and 100% schema description coverage, so the description doesn't need to explain return values or parameters. The formula parameter is complex, but the schema's example covers it thoroughly. The description is complete enough for an agent to understand the tool's purpose, though it could mention that formula tokens reference datasource metrics from describe_datasource.

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 (name, formula, symbol) in detail. The description adds the high-level concept of a 'formula over other metrics' but doesn't add meaning beyond the schema's extensive formula token documentation. The schema's formula example is particularly rich, so the description's contribution is minimal. 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?

The description states a specific verb ('Create') and resource ('calculated metric'), and defines it as 'a custom KPI from a formula over other metrics.' This clearly distinguishes it from sibling tools like add_calculated_metric_widget (which adds a widget to a page) and update_calculated_metric (which modifies an existing one).

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

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

The description implies the tool is for creating a calculated metric, and the schema's formula example shows how to construct one. However, it does not explicitly state when to use this tool versus alternatives like add_calculated_metric_widget or update_calculated_metric, nor does it mention prerequisites like needing datasource IDs from describe_datasource. The usage context is implied but not explicitly guided.

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 indicate that this is a mutating but non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds no behavioral context beyond the word 'create', such as side effects, defaults, duplicate handling, or whether the client is immediately available.

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 short sentence, but it merely restates the tool name and title. This is under-specification rather than earned conciseness, so it does not warrant a higher score.

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

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

Given the close sibling create_client_with_report, the description provides no context for choosing between them. The schema and output schema offer substantial detail, but the description itself fails to give enough guidance for correct tool selection or expected behavior.

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 is documented with meaningful detail, including the currency pattern and the server-filling behavior. The description itself adds no parameter information, but the baseline of 3 applies because the schema carries the full semantic load.

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

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

The description states a specific verb ('create') and resource ('client'), so the core purpose is immediately clear. However, it does not distinguish this from the sibling create_client_with_report, so it falls short of a top score.

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

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

No guidance is given about when to use this tool versus create_client_with_report, update_client, or archive_client. There is also no mention of prerequisites, such as required permissions or how folders and manager relate to the creation flow.

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

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

Goes beyond annotations by explaining the resolution precedence and the important warning that omitting both options never creates a blank report. The only minor gap is the lack of an explicit precedence statement when both template_id and blank:true are supplied together.

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

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

Three sentences, no filler, and the key behavior is front-loaded. Every sentence earns its place by adding resolution logic or practical guidance.

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

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

For a composite creation tool, the description covers the decision branches, warns against unintended blank reports, and points to the right template search path. With an output schema present, return details are not required; only the combined-option ambiguity keeps this from being fully 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 meaningful semantics for template_id, blank, and type, including the list_templates filtering hint. It does not add new meaning for name/report_name/website/timezone, but those are already described in the schema.

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

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

The description states a specific action and resources: 'Create a new client and its first report or dashboard in one step.' It clearly differentiates from siblings like create_client and create_report by emphasizing the one-step combined behavior.

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

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

Provides clear conditional guidance: use template_id to clone, blank:true for empty, and neither to clone a matching Starter template. It also directs users to list_templates for specific styles. However, it does not explicitly state when to prefer separate create_client/create_report calls instead.

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

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

Annotations only indicate non-read-only and non-destructive behavior. The description adds meaningful behavioral context: re-using an existing name updates that connection's credentials, the first call returns the field list, and unsupported datasources 'say so'. This goes beyond the annotations without contradicting 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?

Five sentences carry the full workflow: purpose, first call, second call, upsert caveat, unsupported datasources, and follow-up tools. There is no filler, and the most useful guidance appears early.

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, rich schema descriptions, and annotations, the description completes the picture: it explains the two-step interaction, the credential-only scope, the reuse/update behavior, and downstream tools to call. An agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds important semantics: datasource_id alone triggers a field-discovery response, credentials are provided in the format the tool lists, and name is needed on the second call. This enriches the structured schema meaningfully.

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

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

The description states a specific verb and resource: 'Create a datasource connection from credentials.' It also differentiates this tool from related siblings by noting that link_datasource and test_connection are used afterwards, and that OAuth-based datasources cannot be created here.

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

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

It gives explicit when-to-use guidance: call with just datasource_id to discover required fields, then call again with credentials and a name. It also states a clear exclusion — vendor-website OAuth datasources like Google and Meta cannot be created this way — and names the follow-up tools to use.

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 readOnlyHint=false, so the create/mutating nature is expected. The description adds the row source and the 10,000-row limit, but does not disclose other behavioral details such as whether the dataset is linked to a report, how duplicates are handled, auth requirements, or effects on existing data. It 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, well-structured sentence that front-loads the primary action and object, and includes a relevant constraint in parentheses. Every word adds value and there is no redundancy.

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

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

Given that all parameters are fully described in the schema and an output schema exists, the description is sufficient for an agent to understand the tool's core purpose and input format. A brief note on when this dataset creation is needed relative to other custom-data operations would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline applies. The description mentions 'parsed CSV rows' which helps contextualize raw_data and columns, but it does not add meaningful parameter information beyond the schema's own descriptions. No additional semantics are provided.

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 ('Create') and a specific resource ('custom-data dataset'), and adds the distinguishing source ('parsed CSV rows, max 10,000'). It clearly communicates what the tool does, though it does not explicitly compare itself to sibling tools such as create_asset or 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 implies when to use the tool: when a custom dataset needs to be created from already-parsed CSV rows. However, it does not mention any exclusions, prerequisites, alternatives, or why one would choose this over related create operations, so usage guidance is only implicit.

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

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

With readOnlyHint=false, the annotations already indicate this is a mutating operation. The description adds no further behavioral details, such as whether creating a sender will fail if the domain is unverified, or what side effects occur. It does not contradict annotations, but it provides no value beyond the structured metadata.

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 sentence of four words, making it extremely concise and front-loaded. However, it is so terse that it sacrifices informative content, though it avoids redundancy with the schema. It earns its place by stating the core action, but it could include a brief elaboration without becoming bloated.

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

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

Despite having an output schema and a complete input schema, the description omits important contextual information such as prerequisites, limitations, or how the created sender integrates with other email operations. An agent would need to consult documentation or infer behavior from sibling tools like verify_email_domain and set_default_email_sender. This is inadequate for a create operation with multiple optional postal fields that have legal implications.

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 complete descriptions for all 8 parameters (100% coverage), including enums and supplementary details like anti-spam law requirements for address fields. The description adds no parameter-specific meaning, so it maintains the baseline score of 3 expected when schema descriptions are comprehensive.

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 'create' and the resource 'From sender', which clearly identifies the action as creating a sender entity. However, it does not explain what a 'From' sender is or differentiate it from related sender operations beyond the create verb. The phrase is a slight elaboration on the title but lacks specific context about the sender's role in email delivery.

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 guidance on when to use this tool versus alternatives like update_email_sender, set_default_email_sender, or delete_email_sender. There is no mention of prerequisites such as domain verification or how this sender will be used in future email sends. An agent must infer usage context from the tool name and sibling 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 indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive action. The description adds no behavioral context beyond the verb 'create' – such as whether duplicate names are rejected, whether templates become immediately available, or any side effects. With no extra context, the description fails to add value 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?

The description is a single, directly front-loaded sentence with no filler. It is concise, but it is so terse that it omits useful context that could be added without bloat, so it doesn't reach the maximum.

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 input schema (5 params, 100% coverage) and an output schema, an agent can likely invoke the tool correctly based on structured data alone. However, the description offers no explanation of how this template creation fits into the broader workflow (e.g., with send_email) or how it differs from the generic create_template sibling, leaving a moderate gap.

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

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

Schema description coverage is 100%, so each of the five parameters already has a descriptive explanation. The tool description does not add any additional parameter semantics, but the baseline of 3 is appropriate because the schema fully compensates.

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 'Create an email template' clearly identifies a specific verb and resource, making the tool's basic function unmistakable. However, it does not differentiate itself from sibling 'create_template' or related 'update_email_template' tools, so it earns a 4 rather than 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?

The description provides no guidance on when to use this tool versus alternatives like create_template, update_email_template, or set_default_email_template. There are no mentions of prerequisites, target users, or context such as whether this creates a global or client-scoped template.

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 readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write operation. The description adds no further behavioral context (e.g., prerequisites, side effects, uniqueness constraints), but given the annotations, 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?

A single, front-loaded sentence with zero fluff. It states the action and object clearly, which is the ideal length for a simple create 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 tool with one parameter and an output schema, the description is minimally sufficient, but it lacks any context about folder hierarchy, naming constraints, or relationship to other client operations. Given the simplicity, a 3 is fair but not higher.

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 parameter 'name' is fully documented as 'Folder name'. The description does not add any additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description 'Create a new client folder' uses a specific verb and resource, and the qualifier 'client' clearly distinguishes it from siblings like create_media_folder. An agent can tell what this tool does without opening the schema.

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

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

There is no guidance on when to use this tool versus alternatives such as create_media_folder or update_folder. The description implies it's for client folders but does not state when this is the right choice or when to avoid 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?

The description adds a definition of a goal (target value + comparison for a saved metric query), which gives some behavioral context beyond the tool name. Annotations already indicate it is not read-only or destructive, and the description confirms it is a creation operation. However, it does not disclose potential side effects (e.g., impact on reports), permission requirements, or whether the goal is immediately persisted. With minimal annotation coverage, the description carries the responsibility for these details but fails to provide 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?

The description is a single, tightly worded sentence with zero filler. It immediately states the action and defines the core concept, making it highly efficient and front-loaded. 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 tool has 8 parameters, nested objects, and an output schema, yet the description is minimalist. While the schema is highly detailed and covers parameter semantics, the description lacks high-level usage context such as how the query relates to goal creation or what constitutes a valid setup. Since an output schema exists, not explaining return values is acceptable, but the description could still provide more context on prerequisites and relationship to saved queries.

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%, meaning every parameter already has a description. The tool description adds no additional parameter-level meaning, so it meets the baseline expected for high schema coverage. No extra value is provided beyond what the schema already communicates.

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 (create), the resource (goal), and defines a goal as a target value plus comparison for a saved metric query. This precisely distinguishes it from sibling tools like update_goal, duplicate_goal, or add_goal_widget, leaving no ambiguity about what operation is performed.

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 guidance on when to use this tool versus alternatives such as add_goal_widget or update_goal. It does not mention prerequisites (e.g., needing a saved query), nor does it explain the context of goal creation. A single sentence with no usage context leaves the agent to infer when and why to invoke 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?

The annotations indicate readOnlyHint=false and destructiveHint=false, which already imply a write operation. The description adds no extra behavioral traits, such as whether duplicate names are allowed, parent-folder requirements, or permission needs. For a creation tool, this is sparse.

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 zero filler. It is front-loaded and easily parsed, making it highly concise and well-structured for an agent to digest quickly.

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?

Although the tool is simple, the description lacks sufficient context about when to use it, what a 'media folder' is in the broader system, or any side effects of creation. The presence of sibling tools like create_folder and update_media_folder makes this ambiguity more impactful.

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 'name' is fully described in the schema ('Folder name'), so schema coverage is 100%. The description adds no supplementary meaning beyond what the schema already provides, matching the baseline expectation.

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

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

The description specifies a clear action ('Create') and resource ('a new media folder'), which is unambiguous on its own. However, it doesn't explicitly distinguish itself from the sibling create_folder, so it relies on the reader to note the 'media' qualifier.

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 like create_folder, update_media_folder, or list_media_folders. The description simply states the action without any context or exclusions.

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

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

The description discloses a useful behavioral detail beyond the annotations: pages are appended at the end by default. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false), and the write nature is consistent with 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?

The description is two short sentences with no filler. The core action is front-loaded, and the only additional behavior mentioned (append by default) is relevant and concise.

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

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

Given the high schema coverage, an output schema, and annotations indicating a non-read-only, non-destructive mutation, this description is largely sufficient for an agent to invoke the tool correctly. It could explicitly note that the page is added to an existing report/template, but the required source_id and source_type parameters already convey 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 schema already documents all parameters and their meanings. The description echoes the report/template target and the append-by-default position behavior, but it does not add substantial new parameter-level detail 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 uses a specific verb ('Add') and names the exact resource ('a page') and target ('report or template'), which clearly distinguishes it from siblings like create_report, add_report_section, update_page, and delete_page. It is not a tautology and goes beyond 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?

The intended context is implied: this tool adds a page to an existing report or template. However, there is no explicit guidance about when to choose this tool over related alternatives such as add_report_section or create_report, and no exclusions are stated.

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