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

The description discloses critical behavioral traits: interactive browser opening, storing the token locally, showing expiry, and printing a manual URL in headless environments. This goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=true, etc.) to give the agent a complete picture.

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

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

The description is three concise sentences, front-loaded with the primary action ('Opens a browser window...'). Every sentence adds valuable context without verbosity.

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

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

The description fully covers the tool's operational context: environment requirements, interactive flow, token storage, result contents (expiry), and manual fallback. It is sufficient for an agent to decide when and how to invoke it.

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

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

The tool takes zero parameters, so the schema is fully covered and there is nothing for the description to explain. The baseline score of 4 applies here.

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 function: it opens a browser window to the PushEngage dashboard for authorization. This distinguishes it from the sibling auth tools (status, logout) by describing the unique OAuth login flow.

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 mentions the browser requirement and the fallback for headless/SSH environments, giving clear context for when manual intervention is needed. It doesn't explicitly contrast with auth_status or auth_logout, but the usage context is implied sufficiently.

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 goes beyond the annotations by detailing both server-side revocation and local token deletion, and it explains the post-condition that re-authentication is needed. This provides rich behavioral context beyond the destructiveHint and idempotentHint annotations, with no contradictions.

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

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

The description is extremely concise, consisting of two sentences that pack essential information: the core action and the crucial consequence. Every word earns its place, with no redundancy or filler.

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

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

Given the tool's simplicity (no parameters) and the presence of an output schema, the description fully covers the tool's impact and side effects. It tells the agent exactly what to expect, including the need to re-login, making it complete in 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?

The tool has zero parameters, so the schema imposes no semantic burden. The description does not need to explain parameters; the baseline of 4 applies as the description fully clarifies the tool's behavior.

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

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

The description uses specific verbs 'Revokes' and 'deletes' to identify the action, and clearly specifies the resources affected: the server session and locally stored token. This unambiguously distinguishes it from sibling tools like pushengage_auth_login and pushengage_auth_status.

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 states the consequence for subsequent tool usage: all site-scoped tools require a fresh login. This gives clear guidance on when the tool is appropriate and what will follow, though it does not explicitly reference alternative tools like auth_status. This is strong contextual 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 value beyond the readOnlyHint annotation by listing the exact response fields (authenticated, expires_at, current_site_id, etc.) and clarifying its role in the authentication flow. It doesn't describe error behavior, but for a read-only status endpoint this is adequate given the annotations already signal no destructive 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: one listing the returned fields and one providing usage guidance. It is front-loaded with the core purpose, contains no redundant phrasing, and every sentence adds essential information.

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

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

For a simple read-only status tool, the description is complete. It names all return fields, states the purpose (checking authentication before other calls), and the output schema is available to detail types. There is no missing critical information for an agent to 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 tool has zero parameters, so the schema provides no parameter information. The description doesn't need to explain parameters, and the description clarifies the meaning of the tool's output fields, which serves as semantic context. The baseline for zero-parameter tools is 4, and that fits here.

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 'Returns the current login state' and enumerates the exact fields returned, such as authenticated, expires_at, current_site_id, and api_url. The verb 'Returns' combined with the resource (login/site status) is specific and distinguishes it from siblings like pushengage_auth_login and pushengage_auth_logout.

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 states when to use the tool: 'Use this to check whether pushengage_auth_login is needed before making other calls.' This provides clear usage context and directly ties to an alternative tool (login), making it easy for the agent to choose between them.

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

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

Beyond the annotations, the description discloses a critical behavioral trait: PushEngage caps each site at 50 attributes and the API returns 422 when exceeded. It also explains the relationship between the created key and audience-group rules, adding context that annotations do not provide. It doesn't mention auth requirements or response shape, but the output schema covers the response.

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 four sentences long, front-loaded with the main purpose, and every sentence adds value: required fields, key format, audience-rule integration, and limit behavior. No unnecessary words or repetition of schema data.

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

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

Given a fully documented schema, annotations, and an output schema, the description covers the essential behavioral constraints (key format, limit, audience-rule usage). It doesn't describe the success response, but that is already provided by the output schema. The only minor gap is lack of explicit guidance on when not to use this tool, but overall it is contextually 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% with detailed descriptions and examples for all three parameters. The description adds some contextual meaning (e.g., the audience-rule usage) but largely restates what the schema already provides. The 50-attribute limit is not a parameter-specific detail, so the added value on parameter semantics is marginal; baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Creates a new subscriber attribute on the current site.' It distinguishes itself from siblings like create_segment and create_audience_group by explicitly naming the resource (attribute) and providing meaningful details (required name/key, examples).

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?

Clear context is provided: it explains that the created key becomes usable in audience-group rules, and notes the 50-attribute cap. However, it does not explicitly state when to use this tool over alternatives or when not to use it, so it falls short of the 'explicit exclusions/alternatives' bar.

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 a write operation (readOnlyHint=false) and non-destructive behavior. The description adds valuable context on the filter expression semantics, such as how rules within and across groups combine, and includes examples. It does not reveal side effects like duplicate handling, but annotations cover the safety profile.

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

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

The description is well-structured and front-loaded with purpose. It uses compact notation for the filter schema, provides efficient examples, and every sentence adds value. The usage caution at the end is a worthwhile addition without bloat.

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

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

For a tool with a complex nested filter parameter, the description is highly complete: it explains the creation context, required parameters, filter semantics, and common patterns. An output schema exists, so return values are covered elsewhere. It does not discuss alternatives, but that gap is minor given the overall guidance.

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

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

With 100% schema coverage, the baseline is 3, but the description goes far beyond by explaining the nested filter structure in plain language, providing three complete examples, and advising when to set description and complex filters. This makes the parameters much easier to use correctly.

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

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

The description clearly states 'Creates a new audience group on the current site' with a specific verb and resource, and distinguishes from sibling tools like list_audience_groups. It also names the required parameters, making the tool's 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?

Provides clear context for when to use (creating an audience group) and offers concrete filter patterns for common use cases. It does not explicitly mention alternatives or when-not-to-use, but the purpose is distinct among siblings and the guidance is sufficient for most scenarios.

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 description's 'Creates' is consistent. It adds meaningful behavioral context by explaining the default evaluation timing (only on subscribe) and how add_segment_on_page_load changes it, plus the rule syntax. It does not cover edge cases like duplicate names, but the annotations cover the safety profile and the output schema covers response 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 compact: three sentences front-loaded with the core purpose, followed by criteria syntax, then the page-load behavior nuance, and a closing guardrail. Every sentence serves a distinct informational purpose with no redundancy or filler.

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

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

Given the tool's complexity (nested objects, 4 params, output schema present), the description covers the essential behavioral aspects: what the tool does, the criteria rule format, the default and alternative evaluation behavior, and when to include optional fields. The output schema handles return-value descriptions, so no gap remains.

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 well-documented. The description adds usage-level guidance (when to include optional parameters) but does not enrich semantic meaning beyond what the schema provides. The rule syntax and defaults are reiterated, which is helpful but not additive to schema knowledge.

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 ('Creates a new segment on the current site'), immediately distinguishing it from listing or updating tools. It clearly identifies the creation action and the resource type (segment), and the sibling context (e.g., list_segments) reinforces this distinction.

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

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

The description gives clear context on when to use this tool: when creating a segment, with optional criteria. It explicitly instructs 'Only include segment_criteria and add_segment_on_page_load when the user explicitly describes the matching rules,' which is a valuable guardrail. However, it does not explicitly name alternatives or conditions where another tool (e.g., create_audience_group) might be preferred, though the segment-specific scope is implicitly 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=true, so the read-only nature is known. The description adds valuable context about the scope: 'all-time, site-wide totals' and the exact metrics returned, including the nuance that subscribers is a 'current active count'. It does not contradict annotations and provides useful behavioral detail beyond what the annotation alone offers.

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

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

The description is two sentences long, front-loaded with the core purpose and result, followed by a useful clarification and alternative. Every sentence earns its place with no filler or redundancy.

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

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

Given the tool's simplicity (one optional parameter, read-only, with an output schema), the description covers all essential context: what is returned, the site-wide scope, the all-time nature, and a pointer to the time-series tool for different needs. The output schema handles return value details, so nothing 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% coverage for the one parameter (site_id) with a clear description ('Override the currently selected site.'). The tool description itself adds no extra parameter semantics beyond the existing 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 uses a specific verb 'Returns' and names the exact resource: 'current site's all-time, site-wide totals' with a list of included metrics (subscribers, notifications sent, views, clicks, goal conversions/value). It clearly distinguishes itself from the sibling pushengage_get_analytics_timeseries by explicitly stating it is not bounded by date range.

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 states when to use this tool: for all-time site-wide totals, and explicitly points to an alternative ('for trends over a period use pushengage_get_analytics_timeseries instead'). This gives the agent clear decision criteria between the two analytics 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 declare readOnlyHint and openWorldHint, and the description adds meaningful behavioral context: returns time-series data with specific metrics (subscribers gained, notifications sent, etc.) and bucketing behavior. No contradictions. Slightly less than 5 because it doesn't mention edge cases like empty ranges or timezone handling, but these are covered by output schema.

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

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

Two sentences, front-loaded with purpose, no fluff. Each sentence adds value: first describes output, second gives usage guidance and alternative.

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, the description covers purpose, usage, key metrics, and alternative. The tool is moderate complexity, and the description fills all contextual gaps beyond the schema and annotations.

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

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

Schema coverage is 100%, with each parameter (start_date, end_date, group_by, site_id) already described. The description adds minimal extra meaning beyond mentioning 'bucketed by group_by', which the schema already states. 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 uses a specific verb ('Returns a time series') and clearly identifies the resource (current site's analytics) with date range and grouping. It distinguishes from the sibling summary tool by explicitly noting it's for trends/metrics over a period.

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

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

Explicitly states when to use this tool ('for trends or metrics over a period') and names the alternative ('for all-time totals use pushengage_get_analytics_summary instead'), providing clear guidance and exclusion.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, lowering the bar. The description adds context beyond annotations by detailing the exact structure of the returned data (utm_parameters, fallback_notification, fallback_attributes, default_expiry) and noting that these are the defaults applied to push campaigns. No contradictions with annotations.

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

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

The description is concise and well-structured: a first sentence states the primary function, followed by a parenthetical list of fields and a closing clause that grounds the tool's purpose. Every sentence adds value, with no redundancy or filler.

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

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

With an output schema present and annotations indicating read-only behavior, the description is largely complete. It explains the return structure and the tool's relationship to the dashboard, but could be slightly enhanced by explicitly noting the optional site_id override behavior, though that is covered in the input schema. Overall, it is thorough for a simple read operation.

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

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

Schema description coverage is 100% for the sole parameter site_id, which is described as 'Override the currently selected site.' The description does not mention this parameter, but the schema already provides sufficient semantics, so the baseline of 3 applies. The description adds no extra parameter context 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 clearly states the tool's function: 'Returns the current site's campaign default settings' and enumerates the exact fields returned. This distinguishes it from the sibling 'update_campaign_defaults' tool, as the verb 'Returns' and the focus on reading defaults makes the read-only purpose 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 conveys when to use this tool—when you need the current campaign defaults—and notes that these match the dashboard's Campaign Defaults page. It does not explicitly name the update counterpart or provide exclusions, but the context is clear enough for an agent to select this over the write sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds context about the source page (Advanced Settings) and provides human-readable labels for the returned fields, which clarifies the data semantics 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, efficient sentence that front-loads the main action and uses a parenthetical list to explain field name mappings. No words are wasted; every element 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?

Given the tool's simplicity (one optional param, read-only annotations, and presence of an output schema), the description fully covers what the tool does and what it returns. It doesn't need to explain return structure since the output schema exists.

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 site_id is fully described in the schema ("Override the currently selected site."), and the description doesn't add further parameter-level detail. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns the current site's Service Worker Settings from the Advanced Settings page, with a specific verb "Returns" and precise resource. It also lists the exact fields returned, distinguishing it from the sibling update_service_worker_settings tool.

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

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

The description makes the tool's read-only purpose clear ("Returns the current site's...") and implies it should be used to fetch settings, while the update sibling is for modifications. However, it doesn't explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds the specific fields returned and the 'current site' concept, but doesn't disclose behavioral traits like permission requirements or error handling. Moderate context beyond 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. It front-loads the action and then lists the returned fields, with no redundant or filler content.

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

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

For a simple getter tool with an output schema and read-only annotations, the description provides sufficient information: it identifies the resource and the fields returned. It doesn't elaborate on behavior when no site is selected, but this is a minor gap given the schema's site_id hint.

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 the single optional site_id parameter with a clear description ('Override the currently selected site') at 100% coverage. The tool description adds no extra parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states 'Returns the current site's details' with a specific resource (site details) and lists the exact fields returned. It distinguishes from sibling 'pushengage_update_site_details' by using 'get' vs 'update'.

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 fetching the current site's details, matching the dashboard page. It doesn't explicitly mention alternatives or when not to use it, but the verb 'return' and the optional site_id override make the usage context clear. The sibling tool list provides implicit distinction.

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

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

Beyond the readOnlyHint annotation, the description adds useful behavioral context: it clarifies that attributes are custom keys set via the JS SDK, notes that results are paginated with `has_more`, and mentions that it operates on the current site. This adds value beyond the structured 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 sentences, front-loaded with the action, and every clause adds value: the resource, the data source, pagination behavior, and the concrete use case. No wasted 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 read-only list tool with good annotations, a full output schema, and detailed parameter descriptions, the description covers the essential aspects: what it lists, the pagination flag, and why you'd use it. Nothing critical is missing for the 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 schema already covers all four parameters with detailed descriptions (100% coverage), so the description carries no burden to explain parameters. The baseline of 3 applies because the description does not add any additional 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?

The description uses a specific verb ('Lists') and a specific resource ('subscriber attributes'), with scope ('on the current site') and a distinguishing feature (paginated with `has_more`). It clearly differentiates from sibling tools like list_segments or list_audience_groups.

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: 'Use this to discover attribute `key` values before constructing an audience-group filter rule with field="attributes".' This clearly states a key use case, but does not mention alternatives or when not to use the tool. It falls just short of the 'explicit when/when-not/alternatives' standard.

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

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

Annotations already declare readOnlyHint: true and openWorldHint: true. The description adds valuable behavioral context beyond that: it notes pagination via `has_more` and explains the relationship of returned IDs to other tools (send_notification/send_ab_notification). This is useful supplementary transparency.

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

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

Two concise sentences deliver the core purpose, pagination detail, and a practical usage hint. 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?

The description is complete for a read-only list tool: it covers purpose, pagination, and the practical downstream use case of retrieving IDs. With a full input schema, output schema, and strong annotations, there are no significant 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 all four parameters already have detailed descriptions. The tool description does not add parameter-specific semantics beyond what the schema provides, so it earns 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?

The description states a specific verb and resource ('Lists audience groups on the current site') and clearly distinguishes from siblings like pushengage_create_audience_group and pushengage_list_segments. Mentioning pagination adds scope 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?

It explicitly says when to use this tool: 'Use this to look up audience-group IDs when the user references a group by name'. However, it does not mention alternatives or when not to use, so it falls short of a full exclusionary 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful behavioral context: pagination with a `has_more` flag, and a summary of the fields each item includes. This goes beyond the annotations by explaining the return payload structure, 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?

Three sentences, each with a distinct purpose: action + pagination, definition of the resource, and what each item contains. No filler or repetition. The information is front-loaded with the core purpose first, making it easy to scan.

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

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

For a read-only list tool with a rich output schema, the description is complete enough. It covers the resource, pagination behavior, and the kind of data returned. The existing output schema handles return-value details, and the annotations cover safety, so nothing critical is missing.

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

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

The input schema provides descriptions for all 5 parameters with 100% coverage, including defaults and constraints. The tool description itself does not add parameter-level details, but the schema already does the heavy lifting. The description's mention of pagination and item fields is peripheral to the parameters, so a 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 starts with a clear verb+resource combination: "Lists the chat widgets on the current site." It also clarifies what a chat widget is, distinguishing this tool from other list tools in the sibling set. The scope is explicit (current site, paginated), leaving no ambiguity about the tool's function.

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 clear context for when to use this tool: whenever you need to see the chat widgets configured on the site. It does not explicitly mention alternatives or exclusions, but the purpose is so specific that it implicitly separates itself from other list tools. A brief note about when not to use it or an alternative would push this to 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?

Beyond readOnlyHint and openWorldHint annotations, the description discloses meaningful behavioral details: response includes has_more, include_analytics triggers an extra lookup per page, and the analytics object fields are listed. This gives the agent a clear picture of side effects and cost implications.

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

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

Two well-structured sentences front-load the main action and then efficiently cover filtering, analytics cost, and returned fields. Every sentence earns its place with 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?

Given the output schema exists and annotations provide safety context, the description covers all key aspects needed to invoke correctly: resource type, pagination, optional filters, analytics behavior, and result shape. No significant gaps remain.

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

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

Schema covers all parameters with descriptions, so baseline is 3. The description adds contextual semantics by noting status 'all' mirrors dashboard filter tabs and by emphasizing the trade-off of include_analytics, which slightly boosts 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?

Specific verb 'Lists' identifies exact resource: drip autoresponder campaigns on the current site, with pagination and status filtering. This clearly distinguishes it from sibling list tools like list_triggered_campaigns and list_rss_campaigns.

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

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

Provides clear context: when to use on current site, pagination, filter by status, and when to set include_analytics (only for stats/performance). However, it does not explicitly compare to alternative list-campaign tools or mention when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavior: newest-first ordering, pagination with has_more, the extra lookup cost of include_analytics, the contents of each item (content, status, targeting, delivery stats), and the meaning of absent criteria. No contradictions with annotations.

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

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

The description is three well-structured sentences, front-loaded with the action and result. It covers purpose, usage, key behaviors, and parameter trade-offs without redundancy. Every sentence contributes information.

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

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

Given the tool's complexity (9 optional parameters, output schema present), the description is comprehensive. It explains return item contents, pagination mechanics, analytics cost, and cross-tool integration with send tools. The output schema covers return structure, so the description needn't repeat it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining that include_analytics 'costs an extra lookup' and merges rolled-up counts and goal conversions—details not present in the schema. It also contextualizes pagination via has_more, which enriches parameter understanding.

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

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

The description clearly states the tool lists push notifications on the current site, newest first, with pagination. It explicitly mentions discovering notification IDs and reviewing past/upcoming sends, distinguishing it from sibling tools like list_sites or list_segments.

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 use cases ('discover notification IDs and review past or upcoming sends') and a clear directive for when to enable include_analytics ('only when the user asks for stats'). It also links to send tools via reusable audience_groups ids, but does not explicitly state alternatives like 'use get_analytics_summary for aggregated stats'.

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 it as readOnly and openWorld, so the safety profile is known. The description goes beyond annotations by disclosing pagination behavior via `has_more`, the inclusion of `feed_url` per item, and the status filter semantics mirroring dashboard tabs, providing useful operational context without contradicting the annotations.

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

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

The description is three concise sentences, front-loaded with the main purpose, followed by specific details. Every sentence earns its place without redundancy or 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 read-only list operation with a complete schema and annotations, the description adequately covers the resource type, pagination, filter behavior, and item contents. The presence of an output schema means return values need not be described in prose, so no critical 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?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra parameter context beyond what the schema provides, mostly the 'dashboard filter tabs' analogy for status, but does not meaningfully enhance understanding of page, limit, or site_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?

The description uses the specific verb 'Lists' tied to the resource 'RSS auto push campaigns' on the current site, clearly distinguishing it from sibling list tools like list_drip_campaigns and list_triggered_campaigns. It also includes pagination and filter details that further specify the scope.

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

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

The description provides clear context on what the tool does and its parameters (status filter, pagination), and implies it should be used for RSS auto push campaigns specifically. However, it does not explicitly name alternatives or state when not to use this tool, unlike a perfect score would require.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful behavioral context beyond annotations: paginated response with 'has_more' and the specific fields included per item (e.g., current subscriber count). This adds transparency about what to expect when invoking the tool. No contradiction with annotations.

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

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

The description is a single, concise sentence that front-loads the primary purpose ('Lists segments on the current site'). It packs essential details (pagination, response fields) without any wasted words or redundancy. Every phrase 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?

The tool is a simple read-only list operation with an output schema available. The description adequately conveys the scope (current site), pagination behavior, and item fields. With annotations covering safety and open-world semantics, and the output schema documenting return values, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, meaning each parameter (page, limit, site_id, name_contains) already has a detailed description in the schema. The tool description adds little beyond saying 'paginated' and mentioning 'has_more', which is already implied by the page/limit parameter descriptions. Per the baseline for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Lists segments on the current site, paginated.' It specifies the resource (segments), the action (lists), and the scope (current site). This distinguishes it from sibling tools like list_sites or list_attributes. The mention of response fields further clarifies what the tool returns.

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 for when to use the tool: when you need to list segments for the current site. It also implies usage for browsing segments with pagination. However, it does not explicitly mention when not to use it or reference alternatives (e.g., list_audience_groups), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safe read-only nature. The description adds value by specifying the exact return fields and the fact that current_site_id is included, which is not merely repeating annotations. It also implies authentication requirements via 'authenticated user'. No contradictions.

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

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

The description is three sentences, all information-dense. The first sentence states the core action and output fields, the second explains the current_site_id addition, the third provides a practical usage hint. No redundant or filler content.

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

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

For a simple zero-parameter list tool with an output schema, the description covers the essential behavior: what it returns, the extra current_site_id, and a scenario for using site_url. It is complete given the tool's simplicity and available structured information.

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

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

The tool has zero parameters, making parameter semantics trivially covered by the schema (100% coverage). The description provides no parameter details, but since none exist, the baseline of 4 applies. The description does add meaning by explaining output fields, which helps the agent understand the result.

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 lists PushEngage sites accessible to the authenticated user, naming the returned fields (site_id, site_name, site_url, site_status). It also distinguishes itself from pushengage_auth_status by noting it returns current_site_id, and provides a specific use case for site_url in 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?

The description explicitly references the alternative pushengage_auth_status, noting that calling this tool avoids needing a separate auth_status call when checking the active site. It also gives a concrete guideline for when to use site_url in notifications. However, it does not explicitly compare with siblings like get_site_details or select_site, so full exclusion guidance is missing.

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

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

Annotations provide readOnlyHint and openWorldHint, but the description adds substantial behavioral detail beyond these: pagination response includes `has_more`, status defaults to 'all', and include_analytics incurs an extra per-page lookup. It also specifies the analytics object fields (sent, seen, clicked, ctr, goal_count, goal_value), providing transparency about return structure and cost. No contradiction with annotations.

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

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

The description is concise, well-structured, and every sentence serves a purpose: main functionality, pagination, status filtering, and analytics cost/return. It front-loads the core verb and resource, then provides actionable guidance without fluff.

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

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

Given the output schema exists, the description need not explain return values in detail. It covers pagination, filtering, analytics trade-offs, and response format, making it complete for an agent to select and invoke the tool correctly. Complexity is well addressed with clear parameter-specific guidance.

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

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

Schema descriptions already cover all 5 parameters at 100% coverage, so baseline is 3. The description adds context beyond the schema by clarifying the analytics object's fields and reinforcing the cost of include_analytics. It also explains the pagination behavior ('has_more') which enriches the meaning of page/limit parameters.

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

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

The description clearly states the tool 'Lists the triggered campaigns' with specific examples (Price Drop / Inventory Alert / Cart Abandonment) and notes pagination via `has_more`. This specific verb+resource combination distinguishes it from sibling campaign list tools like list_drip_campaigns and list_rss_campaigns.

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

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

Provides clear context for when to use the optional `include_analytics` parameter ('only when the user asks for stats/performance') and notes the status filter mirrors dashboard tabs. However, it does not explicitly mention when to prefer this tool over sibling list tools (e.g., list_drip_campaigns), though the campaign type examples imply 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 valuable behavioral details beyond the readOnlyHint annotation: pagination with has_more, the cost implication of include_analytics, and the shape of the analytics object returned. This is exactly the kind of extra context that helps an agent anticipate side effects and performance.

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

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

The description is two sentences, front-loaded with the primary action, then details about pagination, filters, and analytics. Every sentence earns its place; there is no fluff or redundancy with 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 an output schema exists and annotations provide the read-only hint, the description covers pagination, filter behavior, the special analytics flag, and what analytics fields are included. This is a complete picture for a list tool with five optional parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it reiterates the include_analytics cost and the status filter, both already present in the parameter descriptions. It doesn't introduce new parameter semantics.

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

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

The description begins with a specific verb and resource: 'Lists the workflow automations on the current site'. This clearly distinguishes it from sibling list tools (e.g., list_segments, list_notifications) by naming the exact resource type. It also notes pagination and filtering, which are additional clarifiers.

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 and some explicit guidance, especially for include_analytics ('only when the user asks for stats/performance') and status (mirrors dashboard tabs). It doesn't explicitly contrast with alternative tools, but since siblings target different resources, the purpose already implies when to use it.

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

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

The description adds important behavioral context not in annotations, such as 'Persists across MCP restarts.' This clarifies the stateful mutation effect, complementing the readOnlyHint=false annotation, though it could mention the result of overwriting a previous selection.

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

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

The description is three concise sentences with front-loaded action ('Sets the current site'), followed by persistence and a prerequisite. Every sentence 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?

For a simple state-setting tool with one parameter and an output schema, the description covers the purpose, necessary prerequisite, and persistence behavior. It is sufficiently complete for an agent to use the tool correctly.

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

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

The schema already provides full meaning for site_id ('PushEngage site_id from pushengage_list_sites'). The description references the parameter but does not add new semantic detail beyond what the schema covers, so it meets the baseline.

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

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

The description clearly states it 'Sets the current site' used by all site-scoped tools, and explicitly lists example tools. This specific verb+resource combination distinguishes it from siblings like pushengage_list_sites.

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

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

It explicitly instructs to call pushengage_list_sites first to get a valid site_id, and explains when the selection applies ('when no site_id is provided'). This gives clear, actionable usage context for 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?

Beyond the annotations (readOnlyHint=false), the description explains default behavior (no auto-winner), the intelligent test flow (limited test phase, delay, winner rollout), and a subtle API quirk: 'draft' is conveyed via action query param while body still says status='sent'. This is exactly the kind of behavioral context the rubric 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?

The description is compact yet dense: every sentence contributes essential behavioral or usage information. It front-loads the core purpose, then layers conditional guidance without redundancy. No filler or repetition.

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

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

Given the tool's complexity (nested variant objects, multiple optional fields, status handling, audience targeting, intelligent mode), the description covers all critical aspects. Since an output schema exists, return values need not be explained. The description fully prepares an agent to invoke the tool correctly, including edge cases like draft status.

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 semantic value by explaining when to set intelligent_ab_test and what happens when omitted, and clarifies the meaning of sent_limit_percentage allocation. While many parameter details are already in the schema, this extra guidance about the interplay between parameters justifies a 4.

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 'Creates an A/B notification on the current site with two variants', which clearly identifies the tool's action, resource, and scope. It distinguishes itself from the sibling non-A/B tool (pushengage_send_notification) and explicitly names the required variant_a/variant_b parameters.

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 when-to-use guidance: how to enable intelligent/auto-winner mode, when to include audience_groups, and which status values to use for scheduling/draft. It also warns against adding unrequested optional fields. However, it does not explicitly name sibling alternatives or state 'use this instead of send_notification when A/B testing is needed', though the name makes this inferable.

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 far beyond annotations: it explains default behavior (send immediately, all subscribers), the meaning of status values, mutual exclusivity of scheduling options, timezone interpretation, and the critical instruction not to infer optional fields. This rich behavioral context is not present in the annotations (which only state non-read-only, non-idempotent, non-destructive) and is exactly what an agent needs to avoid misusing the tool.

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

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

The description is long but exceptionally well-structured and front-loaded. It opens with the core purpose, then proceeds through required fields, optional-field constraints, and delivery modes in a logically ordered, scannable format. Every sentence earns its place; the density is justified by the tool's 17 parameters and complex scheduling behavior.

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 (nested objects, 17 params, scheduling modes) and the availability of a full output schema, the description is remarkably complete. It covers all major decision points: send modes, audience targeting, optional-field restrictions, timezone handling, and the site-URL workflow. No critical operational aspect appears 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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema: it calls out required fields, states that optional fields must not be added unless explicitly requested, clarifies the semantics of recurring_schedule (activate vs draft), and explains when send_in_subscribers_timezone is valid. This transforms the schema from a field list into actionable decision guidance.

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 statement: 'Creates and sends a push notification on the current site.' It clearly distinguishes the tool's core action and scope, and the level of detail makes it unmistakable what the tool accomplishes. It also implicitly differentiates from siblings like send_ab_notification by focusing on standard sends.

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 extensive when-to-use guidance: explicit delivery modes, when to use draft vs sent vs schedule, when to pass audience_groups, and an explicit alternative (call pushengage_list_sites for site URL). However, it does not explicitly mention sibling alternatives like send_ab_notification or list_notifications for A/B testing or viewing existing notifications, which would earn a 5.

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

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

The description adds substantial behavioral context beyond the annotations. It explains the merge behavior ('reads the current values and merges your changes'), the constraints on default_expiry total duration, and the required fields when utm_parameters.enabled is true. This goes well beyond the simple readOnlyHint=false and idempotentHint=true annotations. No contradiction with annotations exists.

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

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

The description is compact (about 120 words) and well-structured. It front-loads the purpose, then covers usage, constraints, and return value in a logical order. Every sentence adds value—no filler, no repetition of schema content. The examples are efficient and illustrative.

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 tricky aspects of this tool: the merge model, partial update semantics, expiry restrictions, and cross-field validation. It even provides an example of a partial edit. The output schema exists, so the description appropriately only notes 'Returns the updated settings.' For a tool with nested objects and merge behavior, this is highly complete and would allow an agent to invoke it correctly without further clarification.

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%, providing detailed field descriptions. The description adds cross-field semantics and examples, such as partial edits, the merge behavior, expiry component omission rules, and validation constraints. This complements the schema rather than repeating it, earning above the baseline of 3 but not a 5 because the schema already handles most 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 uses a specific verb+resource: 'Updates one or more of the current site's campaign default settings.' It names the specific groups (utm_parameters, fallback_notification, fallback_attributes, default_expiry), clearly distinguishing it from sibling update tools like update_site_details or update_service_worker_settings. It also states the return value ('Returns the updated settings'), 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 provides clear context on when to use the tool: when you need to change campaign default settings. It explains partial edits are supported and you must pass at least one group. However, it does not explicitly mention alternatives or when not to use it, so it stops short of a 5. The guidance is clear enough for an agent to select this tool over related get/update 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?

The description adds valuable behavioral details beyond the annotations: it reads current values and merges changes (partial update), enforces a validation rule (service_worker_file_path must be non-empty when enable_service_worker_registration is true), and requires at least one field. These traits are not covered by the idempotentHint, readOnlyHint, or destructiveHint 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 compact and well-structured: three sentences that front-load the purpose, then detail the usage pattern, validation rule, and return value. There is no fluff or redundant repetition of schema/annotation information.

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

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

Given the tool's complexity (4 optional parameters, output schema present, good annotations), the description is quite complete. It explains the merge behavior, validation, and return value. It doesn't mention the optional site_id override, but the schema documents that. The output schema covers return structure, so no need for description to repeat it.

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

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

The schema already provides descriptions for all 4 parameters (100% coverage), so the baseline is 3. The description adds important semantics by explaining the partial-update pattern and the at-least-one-field rule, which are not present in the schema properties themselves, thus adding value.

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: 'Updates the current site's Service Worker Settings.' It lists the specific fields that can be changed (enable_service_worker_registration, enable_service_worker_in_subfolder, service_worker_file_path), which distinguishes it from the sibling read-only tool get_service_worker_settings.

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

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

Provides explicit usage instructions: 'Pass only the fields you want to change' and 'Provide at least one field.' It also explains the merge behavior, giving clear context on when to use this tool. However, it does not explicitly name alternatives or state when not to use it, relying on the tool's name and sibling list for differentiation.

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, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: partial update semantics, the paid-plan requirement for remove_powered_by_pushengage, and the return of updated site details. It does not contradict annotations and goes 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 three concise sentences with no filler. It front-loads the main action, then lists the mutable fields and key constraints. Every sentence adds useful information, making it highly efficient and well-structured.

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

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

The description covers the essential aspects: what it does, which fields are affected, partial update behavior, and return value. The site_id override parameter is only in the schema, but the schema's description covers it. Given the simple tool and rich schema/output schema, the description is nearly complete, with only minor omissions like explicit mention of site_id 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 coverage is 100%, so baseline is 3. The description adds extra semantic value by clarifying that at least one field must be provided and by highlighting the paid-plan requirement for remove_powered_by_pushengage, which is not in the schema. It does not restate all parameter descriptions, but effectively supplements them.

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

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

The description clearly states the tool updates the current site's details and enumerates the specific fields (site_name, site_url, timezone, enable_geolocation, remove_powered_by_pushengage). This distinguishes it from sibling tools like get_site_details (read-only) and update_campaign_defaults/update_service_worker_settings (different resources).

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

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

The description provides clear usage context: it updates the current site's details, supports partial updates ('Pass only the fields you want to change'), and requires at least one field. It does not explicitly mention alternatives or when not to use it, but the scope is unambiguous given the tool name and listed fields.

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