SnapWidget

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

Annotations already declare this is a non-readOnly, non-destructive, non-open-world write, so the safety profile is covered. The description adds the meaningful constraint that the target source must be a manual source, but says nothing about duplicate handling, whether the review is published immediately, or what happens if source_id points at a non-manual source.

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

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

A single front-loaded sentence with no filler, and the key constraint (manual source) is included rather than buried. It borders on terse for a 13-parameter mutation tool, but nothing is wasted.

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

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

The rich schema and existing annotations mean the agent can construct a call correctly from structured data alone. However, for a 13-parameter write operation with no output schema, the description leaves open what is returned and how duplicates or invalid source types are handled.

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

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

Schema description coverage is 100%, with all 13 parameters individually documented including formats, bounds, and the platform enum, so the schema carries the parameter burden. The description adds no field-level meaning (e.g., which fields are ignored for certain platforms), so baseline 3 applies.

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

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

"Adds a review by hand (a testimonial) to a manual source" gives a specific verb (adds) and resource (review/testimonial) plus a scoping constraint (manual source) that distinguishes it from the bulk/automated siblings like import_reviews and sync_review_source. It stops short of naming those siblings, so an agent must infer the boundary.

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

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

"By hand" and "manual source" imply the usage context (single, manually entered testimonial rather than an imported or synced batch), which is real guidance but only implied. There is no explicit when-to-use/when-not statement naming import_reviews or approve_pending_reviews as alternatives.

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=true, so the safety profile is covered. The description adds two pieces of behavior beyond that: Google and G2 sources begin an ongoing review sync (a lasting side effect, not just a one-time write), and the feature requires a paid plan. It does not say what the call returns or whether re-adding an existing source errors.

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

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

Front-loaded with the core action, then broken into compact per-type clauses with no filler. The telegraphic style ('type google: name and place_id from find_google_business') is dense but readable; a slightly more structured list form would read better, but nothing is wasted.

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

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

For a create tool with no output schema, the definition covers the important agent-facing facts: how to configure each type, the cross-tool dependency for place_id, the sync side effect, and the plan requirement. The remaining gap is what is returned (presumably the new source id) and whether duplicates are rejected.

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

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

Schema coverage is 100%, so the baseline is 3, and most of the description's parameter text restates the schema descriptions almost verbatim. The one genuine addition is the conditional dependency the schema cannot express — which parameters are required per type — plus the origin of place_id from find_google_business.

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

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

States a specific verb and resource ('Adds a review source') and immediately breaks the operation into its three concrete variants (google, g2, manual), which lets an agent distinguish it from add_review, import_reviews, and update_review_source without opening a schema.

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

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

Gives per-type guidance and explicit hand-offs: manual sources get their reviews via add_review or import_reviews, and the google place_id comes from find_google_business. It also surfaces a prerequisite ('Paid plans'). It stops short of stating when not to use this tool (e.g. re-using an existing source via list_review_sources/get_review_source).

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 the safety profile (not read-only, not destructive, idempotent), so the description's job is to add operation-specific behavior — and it does: approval applies to ALL waiting reviews at once and takes effect on widgets immediately. It does not cover reversibility (how to un-approve) or what the response contains, which keeps it below a 5.

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

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

Two short sentences, zero filler: the action and its effect come first, and the alternative tool is mentioned last as a secondary note. Nothing is redundant with the title.

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

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

For a one-parameter bulk-mutation tool with full annotation coverage, this is essentially complete: intent, scope, side effect, and alternative are all present. The only gap is that no output schema exists and the description doesn't say what the call returns (e.g., count approved or failure per review).

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

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

Schema coverage is 100% and the single source_id parameter is already documented with a pointer to list_review_sources. The description adds nothing about the parameter 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?

States a specific verb (approves) plus resource (every pending review of a source) and the observable effect (they show on widgets immediately). The scope word 'every' signals a bulk operation, which distinguishes it from the single-item update_review sibling.

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

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

Explicitly routes the agent to get_review_source when it wants to inspect reviews beforehand, which is the main decision point here. It stops short of stating exclusions such as what happens when no reviews are pending, so it is clear context rather than a full when/when-not rule set.

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

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

Annotations declare a non-read-only, non-destructive, open-world write, but the description adds what actually matters: the non-YouTube path returns an approval link rather than completing, the link is single-use and valid 24 hours, no SnapWidget sign-in is required, and list_accounts confirms success.

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

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

Front-loaded with the action, then the platform branching, then the link constraints, then the renewal pointer. The parenthetical "(the platforms require this; no SnapWidget sign-in is needed)" and stacked clauses make it dense but every sentence carries operational 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?

No output schema exists, so the description must explain what comes back - and it does, distinguishing an immediately added YouTube account from an approval-link response. It also covers expiry, single-use, and how to verify or renew, leaving no operational gap.

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

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

Schema coverage is 100%, so the enum and channel_url are already documented. The description nonetheless adds meaning the schema does not: channel_url is required in practice for YouTube ("send its link and it is added at once"), while the other services take no URL and instead produce an approval link.

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

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

States a specific verb and resource ("Adds a social account to the user's SnapWidget account") plus the downstream effect on widgets. It is clearly separable from reconnect_account and list_accounts, which it names explicitly.

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

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

Gives explicit when-to-use: connect a new account; and when-not: use reconnect_account for an expired account. It also branches usage by platform (YouTube vs Instagram/Facebook/TikTok/X), removing any inference about which path applies.

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-only, non-destructive, closed-world operation, and the description adds genuinely useful context on top: the copy is a distinct widget with a fresh embed code, and a pro copy consumes the plan's widget limit. That quota/licensing consequence is behavior an agent could not derive from the annotations. It stops short of saying whether the new widget id is returned or how the copy is identified afterward.

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

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

Two sentences with zero filler, and the most decision-relevant facts (what gets copied, that the embed code is new, that it counts against the limit) come first. Nothing is repeated from the title or schema.

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

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

For a one-parameter, no-output-schema tool, the description covers what is duplicated, the identity of the result, and the billing/quota side effect. The only meaningful gap is the return value, which the absence of an output schema would otherwise require the description to explain.

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 widget_id parameter is fully documented in the schema, including a pointer to list_widgets for discovery, so the schema carries the burden. The description adds no additional meaning about the identifier or any constraints on which widgets can be copied. Baseline 3 is appropriate at 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 opens with a specific verb and resource ("Copies a widget") and scopes what is duplicated: settings plus accounts or review sources. It implicitly separates itself from create_widget by defining the copy as a new widget with its own embed code, though it never names the sibling alternatives 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?

Usage is only implied: an agent can infer this is the tool for duplicating an existing widget rather than building one from scratch with create_widget. There is no explicit when-to-use guidance, no stated preconditions, and no note about when copying is preferable to re-creating or updating a widget.

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 is a non-read-only, non-destructive, closed-world write. The description adds real behavioral context beyond them: a new pro widget consumes the plan's widget limit, accounts are capped by the plan, campaigns are Instagram/Pro-only, and review widgets silently filter out hidden and pending reviews. Return shape is also characterized as equivalent to get_widget with a reviews_shown count.

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

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

Front-loaded with purpose, then mode-specific requirements, then post-creation workflow and plan side effect. The prose is dense and somewhat comma-spliced, but each sentence contributes a distinct fact and nothing is 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?

For a six-parameter mutation tool with no output schema, the description covers both usage modes, the prerequisites and their sibling tools, the returned object, the plan-limit side effect, and a post-creation next step. An agent has enough to call it correctly and to interpret the response.

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

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

Schema description coverage is 100%, so the schema already carries the per-parameter meaning and the kind enum default. The description mostly restates that (first account supplies service/header, remaining accounts add posts, source_ids default to all sources) and adds only marginal linkage between source_ids, the "shown" count in list_review_sources, and reviews_shown.

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

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

Opens with a specific verb and resource ("Makes a widget") and immediately splits the operation into its two concrete modes, social and review, each with its required inputs. The agent can distinguish this from get_widget, update_widget, preview_widget and copy_widget without opening any schema.

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

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

Gives a clear workflow: create here, then adjust settings with update_widget, then use get_embed_code to publish. It also names the prerequisite listing tools (list_accounts, list_widget_types, list_campaigns, list_review_sources) that supply valid ids. It stops short of stating when NOT to use this (e.g. duplicating an existing widget via copy_widget), so not 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, so the baseline is covered, but the description adds genuine value by disclosing the cascade (participant list is also deleted) and a blocking precondition about active widgets. It omits irreversibility, permission requirements, and what happens if the guard is violated.

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, and the destructive scope is front-loaded. The second sentence is terse to the point of being slightly cryptic ("Not while a widget shows it" reads as a fragment).

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

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

For a one-parameter destructive tool with no output schema, the description covers the two things an agent most needs: the cascade effect and the widget precondition. Remaining gaps around failure modes and permissions are minor at this complexity.

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

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

Schema coverage is 100% with a single required campaign_id already described as coming from list_campaigns, so the schema carries the burden. The description adds no format, range, or lookup guidance 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?

States a specific verb and resource ("Deletes a hashtag campaign") and adds meaningful scope detail by noting it also removes the joined-people list, which implicitly distinguishes it from the sibling remove_campaign_participant. It stops short of explicitly naming sibling alternatives, so 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?

Provides an explicit when-not condition: "Not while a widget shows it," which is a real precondition an agent would otherwise miss. It does not name an alternative tool or say what to do instead (e.g., delete the widget first), leaving the remedy implicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond restating deletion: it doesn't say the action is irreversible, whether the review can be recovered, or what happens to aggregates/stats tied to the review. For a destructive tool, that is a meaningful missed opportunity even with annotations present.

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 with no padding, front-loaded with the verb, which is good. The brevity here reflects under-specification rather than disciplined conciseness, so it earns no more than an adequate 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?

This is a destructive, single-parameter tool with no output schema, so the description carries the burden of warning about irreversibility and side effects. It says nothing about consequences, permissions, or post-deletion state, leaving an agent without the context needed 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?

Schema description coverage is 100%, and review_id is already documented as 'the id in get_review_source'. The description provides no additional meaning about the identifier, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Deletes a review'), which is understandable on its own. However, the qualifier 'of a manual source' is ambiguous: it isn't clear whether reviews from non-manual sources can also be deleted, or what 'manual source' means in this domain. It does not name any sibling (e.g. update_review, remove_review_source) to differentiate itself.

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

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

There is no statement of when to use this tool rather than update_review (to modify) or remove_review_source (to detach a source). No preconditions such as ownership, review state, or approval status are mentioned, so the agent must infer the call conditions entirely from surrounding 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?

With destructiveHint=true already declared, the description still adds real value: it explains the visible outcome on embedded sites (empty widget rather than a broken embed) and that accounts and review sources survive the deletion. It never states that the deletion is irreversible or what the call returns, which keeps it below 5.

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

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

Four short sentences, action front-loaded, with the risky-confirm rule before the side-effect notes. The phrasing is slightly telegraphic ("a site that still has its code") but no sentence is wasted.

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

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

For a two-parameter destructive tool with a fully described schema, this covers the confirmation gate, the embed-site outcome, and preserved related data. Missing only reversibility and the response shape, which matter for a delete 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 coverage is 100%, so both params are already documented and the baseline is 3. The description merely restates the confirm rule already in the schema's confirm description; its only marginal addition is the instruction to ask the user first.

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?

"Deletes a widget" gives a specific verb plus resource, and the widget resource is clearly distinct from sibling delete tools like delete_review and delete_campaign. It stops short of any scope statement (permanent? cascade?) that would raise it to 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 states a concrete precondition: if the widget had views in the last 7 days the agent must pass confirm: true and ask the user first. That is explicit when/how guidance, but no alternatives (e.g., update_widget to disable instead) 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?

Annotations already declare read-only, non-destructive, open-world behavior, so the safety profile is covered. The description adds entitlement context ('Paid plans') that annotations cannot express, which is genuinely useful. It says nothing about what the lookup returns (candidate list? single match?) or how ambiguous name/city matches behave, which matters for a read that feeds a write.

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 clauses, front-loaded with the action and resource, with no padding. The trailing 'Paid plans.' is abrupt but still earns its place by flagging an entitlement constraint.

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

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

For a two-parameter read with full schema coverage and annotations covering safety, the description is mostly sufficient. However, with no output schema, the agent is left guessing what a successful result looks like and whether it yields an identifier usable by add_review_source — a gap given the stated workflow dependency.

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

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

Schema coverage is 100% and the schema already explains both the combined name+city query format and the country code with an example. The description's 'by its name and city' merely restates the query parameter, adding no new detail beyond the structured fields.

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

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

States a specific verb and resource (finds a business on Google Maps) plus the scoping inputs (name and city), and names the sibling workflow it feeds (add_review_source with type google). An agent can distinguish it from add_review or get_review_source without opening a schema.

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

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

Explicitly ties the tool to a downstream step: use it to locate a business for add_review_source with type google. It gives clear triggering context but no when-not guidance (e.g., what to do if the business already exists as a review source, or if it is not on Google).

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's added context is what matters: it explains the consequence of trial_ends_at ('after it the Pro widgets stop until the user pays') and clarifies that usage.widgets counts only widgets subject to the plan limit. That is real behavioral value beyond the structured fields, though return shape/pagination is still unstated.

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?

Every clause carries information: the plan, the four limit dimensions, the definition of usage.widgets, and the trial consequence with a pointer to get_upgrade_link. It is a single dense run-on sentence with colon-delimited field notes, which is slightly hard to scan and not clearly front-loaded with a verb, but there is no filler.

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

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

With no output schema, the description must carry the return-value burden, and it only documents three of the likely fields (plan limits, usage.widgets, trial_ends_at). It does not say what the plan object contains beyond the limit categories, nor what else the response includes, so an agent cannot fully anticipate the payload.

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 there is no parameter semantics burden and the baseline is 4. The description adds no parameter information, but none is needed.

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 resource: the user's SnapWidget plan, its limits (widgets, accounts per widget, services, layouts), usage.widgets, and trial_ends_at. It reads as a field-by-field statement of what is returned rather than a verb-led purpose sentence, so an agent must infer the action ('get/read the current account'). It does partially disambiguate against siblings by naming list_widgets and get_upgrade_link.

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: call this to check plan limits or whether a Pro trial is active, and it explicitly redirects the payment subtask to get_upgrade_link. However, it never states when to prefer get_account over list_accounts or connect_account, nor any precondition such as requiring an authenticated account.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape of the result (campaign, join link, participants with ids), which matters because no output schema exists. It does not say what happens when the campaign_id does not exist.

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 dense sentence with zero filler; the primary subject (the campaign) is front-loaded and the cross-tool pointer comes last where it is least disruptive.

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

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

For a one-parameter read tool with no output schema, the description covers the essentials by describing what comes back and how the ids are reused. Minor gaps remain around not-found behavior and whether the participant list is truncated, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single campaign_id property is already documented as 'The campaign's id (the id in list_campaigns)'. The description adds no further meaning about the parameter, so the baseline 3 applies.

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

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

The description names the resource precisely ('One hashtag campaign') and enumerates the payload: the join link and the participants with their ids. This clearly separates it from the list-oriented sibling list_campaigns, though it never uses an explicit verb like 'retrieve' or 'fetch'.

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

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

It gives concrete downstream context by saying the returned participant ids feed remove_campaign_participant, which tells an agent why and when to call this tool. It stops short of explicit exclusions (e.g. 'use list_campaigns to discover the id'), so it is clear context rather than 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful return-context (embed code plus platform-specific steps) but says nothing about auth requirements, whether the widget must be published first, or output format. With annotations carrying the safety burden, this is adequate but thin.

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

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

One compact sentence with no filler, front-loading the core resource. It is a sentence fragment rather than a complete statement, but that costs little and brevity is appropriate for a simple read tool.

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

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

For a one-parameter read-only tool with no output schema, the description tells the agent both what is fetched and what extra content (per-platform instructions) comes back, which is the main thing missing from structured fields. Only prerequisites and return format remain unstated, which 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?

The single widget_id parameter has 100% schema description coverage and explicitly points to list_widgets as the source of the id. The description adds nothing beyond the schema, which is fine given full coverage, but means no extra value 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 names the resource (a widget's embed code) and adds that the response includes platform-specific setup steps for WordPress, Wix, Shopify, Squarespace, and plain HTML. That distinguishes it from get_widget or preview_widget, though it is a noun phrase with no explicit verb and never says 'returns' or 'retrieves'.

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

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

There is no when-to-use guidance and no mention of alternatives such as get_widget or preview_widget. The agent must infer from the name and the sibling list that this is the tool for embedding-related needs rather than previewing or editing a widget.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two useful facts beyond that: it returns ids usable by update_review/delete_review and it pages 50 at a time, but it says nothing about ordering, total counts, or what happens with an invalid source_id.

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

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

Two short sentences, zero filler, with the primary return content front-loaded before the pagination note. Nothing here needs trimming.

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 small read-only tool with three fully documented parameters and no output schema, this covers the essentials: what comes back, the page size, and the downstream use of returned ids. The only minor gap is the absence of an explicit pointer to list_review_sources for id discovery, which the schema already supplies.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including defaults and maximums. The description's only added semantic is '50 a page', which duplicates the per_page default already stated in 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?

States a specific verb and resource: returns one review source plus one page of its reviews. The singular 'one review source' implicitly contrasts with the sibling list_review_sources, but the contrast is never made explicit, so an agent must infer that distinction from the name alone.

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

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

Usage is only implied — it returns the review ids needed by update_review and delete_review, which suggests a read-then-mutate workflow, but the description never says when to prefer this over list_review_sources or how to obtain a source_id (that hint lives only in the schema).

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

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

Annotations already establish readOnly, non-destructive, closed-world, so the bar is lower; the description still adds real behavioral context: the link requires no login and carries the prefilled email, and it explains the billing consequence of the trial (first payment at trial end, no second trial). It does not mention link expiry or whether repeated calls produce new tokens, which would be the remaining useful disclosure.

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

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

The what/where is front-loaded and the usage rules are tight, but the trial-billing sentence ('no second trial... first payment is on the day the trial ends') is tangential to invoking the tool. The final sentence about /settings/subscription is useful, so only modest trimming is warranted.

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

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

With a single optional enum parameter and no output schema, the description carries the burden of describing the return value, and it does so (a link, no login required, email prefilled). Combined with annotations and a fully documented enum, an agent has enough to call it correctly; only link lifetime/expiry behavior is missing.

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

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

Schema coverage is 100% and the plan enum already documents all six values with prices and the default. The description never mentions the plan parameter, so it adds no meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly identifies the resource produced: a login-free payment-page link with the account owner's email prefilled, scoped to a paid plan. It distinguishes itself from get_account (used to detect trial expiry) and from /settings/subscription (for accounts already paying). The only weakness is that the 'get' verb is implicit rather than stated, but the artifact is unambiguous.

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

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

It states explicit triggers ('when they want to keep their Pro widgets', 'when get_account shows that the trial ends soon') and an explicit exclusion ('An account that pays already changes its plan on /settings/subscription'). It even names the sibling tool whose output should drive the decision.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real context beyond that by disclosing the shape of the returned data and a conditional field (reviews_shown) that only appears for review widgets, including the edge case that 0 means an empty widget. It stops short of stating behavior on an unknown or foreign widget_id, which would have made it a 5.

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

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

Two short sentences, zero filler, and the returned-field list is front-loaded. The second sentence is slightly elliptical ('A review widget has reviews_shown') but still parses correctly in context.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so by enumerating the fields returned plus one conditional field's semantics. For a one-parameter read tool this is close to complete; only error/not-found behavior is unaddressed.

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

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

Schema coverage is 100% and the single parameter widget_id is already documented in the schema as 'the id in list_widgets'. The description never mentions the parameter at all, so it adds no meaning beyond the structured field. Baseline 3 applies when the schema does all the work.

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

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

The description states a specific resource ('One widget') and enumerates the payload it returns: settings, accounts, embed code, install status and the sites where it shows. That is enough to separate it from list_widgets or get_widget_stats by implication, but it never names a sibling or uses an explicit verb like 'retrieve', so differentiation is inferred rather than stated.

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

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

Usage is only implied: an agent can deduce this is the detail-fetch for a single widget, but there is no when-to-use framing, no pointer to get_widget_stats/preview_widget for other needs, and no note that a widget_id must come from list_widgets (that lives in the schema instead). Adequate but with clear gaps.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds substantial behavior beyond that: the paid-plan gating, that only Pro and review widgets are counted, that visitors is a sum of daily visitors, and the counted_from {date, reason} convention with its 'counting' vs 'widget' reasons. With no output schema, more detail on the response envelope (top-level keys, list names) would be needed for a 5.

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

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

The core scope is front-loaded, but the text is a dense run-on with five clauses chained by commas and colons, mixing purpose, tiering, output shape and edge cases. Every sentence carries information (which matters with no output schema), yet the lack of structure or paragraphing makes scanning harder than it should be.

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

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

For a two-parameter read tool with no output schema, the description does the heavy lifting well: it covers what is returned, aggregation semantics, the 365-day weekly bucketing quirk, and the counted_from partial-coverage case. It stops short of describing the overall response structure (e.g. how daily/weekly lists and the per-widget sections are keyed), leaving a small 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%, and both parameters are already documented in the schema, so the baseline is 3. The description explains the 365-day weekly bucketing and the 'days' field on each week, but that describes output shape rather than adding meaning to the inputs; the from/to and counted_from values it explains are not even input 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 names a specific verb+resource (analytics/stats for the user's widgets) and enumerates the returned dimensions: views, clicks, visitors per day, sites, countries, devices, most-viewed widgets, and per-widget top posts/reviews and Shoppable product clicks. An agent can tell immediately that this is reporting data, not widget configuration as with get_widget/list_widgets.

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 context is implied rather than stated: the phrase 'as the Analytics page shows it (paid plans)' signals the prerequisite that analytics requires a paid plan. There is no explicit when-to-use guidance, no statement of when to use get_widget instead, and no exclusions or note about what happens with zero data.

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

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

Adds real behavior beyond the annotations: a 2 MB payload cap, the header-row requirement, and duplicate-skipping semantics. It does not say whether bad rows abort the whole import or what the response reports, which is the main remaining gap for a mutation 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?

Two tight sentences with the operation and constraints front-loaded and no filler. Slightly dense phrasing ('the text of a CSV file with a header row (2 MB at most)') but nothing extraneous.

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 only two fully documented parameters and no output schema, the definition covers what an agent needs to build a valid call. It leaves unclear what the response contains (counts imported vs skipped) and whether partial failures roll back, which is a modest but real gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a size limit and reiterates the header row, and narrows source_id to manual sources, but gives no format detail beyond the schema's own example.

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

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

States a specific verb and resource ('Imports reviews') plus the input form (CSV text) and the target ('a manual source'). This implicitly distinguishes it from add_review (single review) and sync_review_source (connected sources), though no sibling is named 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 mention of 'a manual source' implies the caller must first resolve a source via list_review_sources, but the description never says when to use this versus add_review or sync_review_source, nor what preconditions the source must meet.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description earns credit by disclosing the payload shape and the meaning of the status field (OK vs expired requiring a reconnect), which is genuine behavioral context an agent can act on. It does not mention ordering, pagination, or whether accounts from all services are included.

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

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

A single sentence that front-loads the resource and then lists the returned fields with no filler. Every clause carries 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?

With no output schema, the description carries the burden of describing return values and does so adequately for a simple zero-argument list tool. Minor gaps: it doesn't say whether results are complete or truncated, nor explicitly what a caller should do when status is expired (reconnect_account).

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to compensate for on this dimension.

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 the resource ('connected social accounts (sources)') and enumerates the fields returned (service, name, status, widgets), which is specific enough to distinguish it from get_account (single) and the various *_account/*_review_source mutations. It doesn't explicitly contrast with siblings like list_review_sources, so it stops short of a 5.

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

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

Usage is only implied: it's evidently the enumeration counterpart to get_account, and the 'expired and in need of a reconnect' note hints that reconnect_account follows. There is no explicit 'use this when...' or 'do not use for...' statement, and no guidance on whether the list is filtered or scoped to the current user.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only that join links come back with each campaign, which is a useful content hint but not pagination, ordering, or volume 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?

A single short fragment that front-loads the resource and its distinguishing payload (join links). It is efficient, though the missing verb makes it read as a caption rather than an instruction.

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

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

For a zero-parameter list tool with no output schema, the description should say whether all campaigns are returned and what fields accompany the join links. It is adequate to identify the resource but leaves the agent guessing about scope and shape of the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly signals that no input is required by framing this as a direct retrieval.

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 phrase names the resource precisely ('Instagram hashtag campaigns with their join links'), but it is a noun phrase with no verb, so the listing action is only inferred from the tool name. It does not distinguish itself from get_campaign, delete_campaign, or the other list_* 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?

No when-to-use guidance is given and no alternatives are named. An agent must guess that this is the bulk-retrieval counterpart of get_campaign, and nothing says whether this is scoped to the authenticated user or their workspace.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the returned fields (date, amount, currency, paid status, receipt link), which is behavior beyond the annotations, but says nothing about ordering, completeness, or auth requirements.

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

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

A single compact sentence with no waste; every item listed is informative. It is a sentence fragment rather than a full statement of purpose, which slightly weakens the front-loading of intent.

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

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

With no output schema, the description must carry the return-value burden, and it does list the key fields. However, it omits whether all invoices are returned or a subset, and any ordering or pagination behavior, which leaves an agent guessing for a list 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?

The tool has no parameters, so the baseline is 4. The description's field list is extra context but not required 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 names the resource ('the user's invoices') and enumerates its fields, so the agent knows what it returns, but it never states the action (list/retrieve) or scope explicitly, relying on the tool name to carry that. It also does nothing to distinguish this from other list_* siblings beyond the resource noun.

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 call this tool, what it returns in aggregate, or what alternatives exist. With zero parameters there is little routing ambiguity, but the description still offers no usage context at all.

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

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

The annotations already declare this as a non-destructive read-only operation, and the description adds useful domain context by defining 'reviews' as all reviews and 'shown' as excluding hidden and pending reviews. It also discloses that sync state and associated widgets are included, which is meaningful 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 compact sentence with no wasted wording, and the key field definitions are packed into the parenthetical. Its sentence-fragment style and nested parentheses slightly reduce clarity, but it remains front-loaded and efficient.

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 list tool with no output schema, the description covers the important returned concepts: review sources, review counts, sync state, and associated widgets. It omits ordering or pagination details, but those are minor for this simple read-only listing.

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 there is no parameter semantics to document. The description does not need to compensate for schema gaps, and the baseline for a zero-parameter tool 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 identifies the resource (review sources) and the aggregate data returned (review counts, sync state, widgets that show them). It is a noun phrase rather than a verb-led statement, but the plural resource and bundled metadata clearly distinguish it from the singular get_review_source.

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 explicit when-to-use guidance, no prerequisites, and no comparison to alternatives such as get_review_source or list_widgets. An agent can infer that this lists all review sources, but the description does not route it against 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, and the description does not contradict them. It adds genuinely useful non-structured behavior: fixed page size of 30, preservation of the widget's display order, and the cursor contract for paging. No detail on what happens with an invalidated cursor, which keeps it at 4.

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

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

Two short sentences, front-loaded with what comes back and how big a page is, followed by the paging action and the exclusion. Nothing is redundant with the title and no sentence is filler.

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

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

With no output schema, the description appropriately carries the return-value burden by listing the fields (image, caption, date, link, alt text, product tags) and the page size. It leaves field shapes and the product-tags structure unspecified, a minor gap for a read-only paginated list.

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

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

Schema coverage is 100%, so both widget_id and cursor are already documented. The description only restates the cursor round-trip that the schema's cursor description already conveys, adding no format, encoding, or edge-case detail. 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?

Names a specific resource (the posts a widget shows), a specific scope (one page of 30, in the widget's own order), and enumerates the returned fields. The closing "Not for feed widgets" separates it from adjacent widget tools such as get_widget and list_widgets.

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

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

Gives explicit pagination guidance ("For the next page, send next_cursor as cursor") and an explicit exclusion ("Not for feed widgets"). It stops short of naming the sibling tool an agent should use for feed widgets, so the routing is only half-closed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantive context beyond that: newest-first ordering, which fields are returned (install status, 7-day views), and the plan gating on the views metric.

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 dense sentence that front-loads the resource and scope, then the returned fields and pagination. Every clause carries information; nothing is redundant.

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

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

With no output schema, the description usefully names the key returned attributes (install status, recent views) so an agent knows what to expect. Minor gaps remain around total counts or pagination termination, but the essential shape is conveyed.

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

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

Schema coverage is 100%, so both page and per_page are already documented including the 50-per-page default and 100 maximum. The description's '50 a page' matches the schema rather than extending it, so baseline 3 applies.

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

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

The description names the resource precisely ('The user's widgets (social and review)') and the ordering ('newest first'), which is enough to distinguish this from get_widget or list_widget_types. It doesn't explicitly state the verb 'list' or name a sibling alternative, keeping it just short of a 5.

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

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

It surfaces one real usage constraint — that the 7-day view data is limited to paid plans — which affects when the returned data is meaningful. There is no explicit guidance on when to use this versus get_widget or how to page through large result sets beyond the '50 a page' note.

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

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

Annotations already declare read-only, non-destructive, and closed-world behavior. The description adds useful return-content context by naming required plans and setting types/allowed values, but it does not cover format, pagination, or error behavior; with annotations present, 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?

It is a single sentence with no wasted words, but it is a sentence fragment rather than a front-loaded declarative statement. The structure could more clearly lead with the action or output.

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

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

With no output schema, the description must convey return values. It lists conceptual contents (services, layouts, plan, settings types and allowed values) but omits the return structure and does not explicitly state that this is an unfiltered reference list.

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

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

The tool has zero parameters, so the baseline is 4. The description appropriately adds no parameter details because none exist.

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 is a noun phrase naming the data returned (services, layouts, plans, settings) rather than stating an action. It identifies widget-type metadata but does not explicitly distinguish it from sibling tools such as list_widgets or get_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?

There is no when-to-use guidance, no mention of alternatives, and no indication of why an agent would call this instead of list_widgets or get_widget. The description gives no context about using it before create_widget or update_widget.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavior: the widget renders live in chat, and in hosts without MCP Apps support the result degrades to a page address. It stops short of saying what the response looks like in the normal case (rendered artifact vs. text).

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

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

Two short sentences, front-loaded with the primary behavior and followed by the fallback case; nothing redundant. The phrasing "the answer has the address of the widget page" is slightly awkward but not wasteful.

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 read tool with no output schema, the description covers both the primary outcome (live preview in chat) and the degraded outcome (URL to open), which is the key thing an agent needs to relay. Only the exact shape of the non-fallback result remains unstated.

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

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

With a single parameter and 100% schema description coverage, the schema already defines widget_id and even its provenance (list_widgets). The description adds no further semantics about format or where to obtain the id, 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?

"Shows the live widget in the chat, as it shows on a site" names a concrete verb (shows/previews) and resource (widget), and the live-rendering framing separates it from config-oriented siblings like get_widget or get_embed_code. It never names those siblings explicitly, so differentiation is inferred rather than stated.

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

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

Usage is implied: the tool is for seeing how a widget looks, and the description notes what happens in environments without MCP Apps support. There is no explicit 'use this instead of get_widget/get_embed_code when…' guidance or stated prerequisite such as having a widget_id from list_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?

Adds substantial behavior beyond the annotations: the call is non-destructive but returns an approval link rather than performing the fix itself, the link must be handed to the user (or account owner), it is single-use and expires in 24 hours, and successful use re-points all of the account's widgets to the new sign-in. Those are exactly the operational facts an agent needs and that readOnlyHint/destructiveHint do not convey. The external platform sign-in described is performed by the human, so it does not meaningfully contradict openWorldHint=false on the tool call itself.

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

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

Four short sentences, front-loaded with purpose and trigger, then the user-facing flow and the expiry caveat. Nearly every clause earns its place; only the parenthetical '(or any Instagram, Facebook, TikTok or X account)' is slightly ambiguous in how it qualifies the expired-account precondition.

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

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

There is no output schema, and the description supplies the return semantics itself ('the answer is an approval link') along with its one-use, 24-hour lifetime. Combined with the single documented parameter and the non-destructive mutation annotation, an agent has everything needed to call it and act on the result.

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

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

Schema coverage is 100% and the single account_id parameter is already documented as 'the id in list_accounts'; the description repeats that same reference without adding format, type, or edge-case guidance (e.g. what happens if the id is not expired). Baseline 3 is appropriate when the schema carries the load.

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

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

States a concrete verb and resource — 'renews an account' — plus the exact entry condition ('that list_accounts shows as expired') and the return value ('the answer is an approval link'). The renewal-vs-initial-connection distinction from the sibling connect_account is implied by 'renews' but never named explicitly, which keeps it just short of a 5.

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

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

Gives clear triggering context: use it for accounts list_accounts marks as expired, and notes it also works for 'any Instagram, Facebook, TikTok or X account'. It also spells out the downstream human step (open link, sign in, click Allow). It never states when NOT to use it — most notably it does not route the agent to connect_account for a first-time connection.

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, but the description adds real value beyond that: the cascade behavior (widgets fall back to their next account, or show no posts if none exists) and the conditional confirm gate based on 7-day view activity. It stops short of stating whether removal is reversible or how to recover from it, which keeps it off a 5.

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

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

Four short sentences, front-loaded with the core action and effect, then the safety workflow. Dense but every clause carries operational meaning; only minor tightening (e.g. the trailing 'ask the user first') could be merged with the prior sentence.

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

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

For a two-parameter destructive mutation with no output schema, the description covers the action, cascade consequences, the safety precondition, and the required pre-call lookup. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description nonetheless adds conditional meaning to confirm by tying it to the 'views in the last 7 days' condition, which is richer than the schema's own phrasing and directly shapes correct invocation.

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

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

States a specific verb and resource ('Removes a social account') and immediately scopes it to SnapWidget accounts, distinguishing it from siblings like remove_review_source, delete_widget, and reconnect_account. It also describes the downstream effect on widgets, so the agent knows exactly what domain object is being acted on.

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

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

Explicitly routes the agent to list_accounts to see affected widgets, instructs it to tell the user before removal, and gives a concrete precondition: confirm: true is required when widgets had views in the last 7 days, and the agent should ask the user first. This is rare, actionable when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a useful post-condition (the person's posts stop appearing in the campaign's widgets) but does not say whether the removal is reversible, whether their collected posts are deleted or merely hidden, or what permissions are required.

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

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

A single sentence that leads with the action and follows with the concrete consequence, with no redundant or filler wording.

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 destructive tool with no output schema, the description covers what happens visually but leaves the important semantic gap of whether the participant's data is deleted or only suppressed, and whether the operation can be undone. Adequate, but not fully complete for a destructive mutation.

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

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

Schema description coverage is 100%, and the schema already explains that campaign_id comes from list_campaigns and participant_id from get_campaign. The description adds no parameter-level 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 states a specific verb and resource ("Removes a person from a hashtag campaign") and adds the observable effect on campaign widgets. It is clearly distinguishable from siblings like remove_review_source or remove_account by naming the affected resource, though it doesn't explicitly contrast with any sibling by name.

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

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

Usage is implied by the action and its stated outcome, but there is no explicit when-to-use guidance, no prerequisites (e.g. campaign must exist or be in a given state), and no mention of the alternative tools for undoing or re-adding a participant.

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

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

Annotations already declare destructiveHint=true, so the safety profile is known; the description nonetheless adds real behavioral context beyond them by disclosing the cascade ('all its reviews') and the downstream effect on review widgets. It does not say whether deletion is permanent or reversible, which keeps it from a 5.

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

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

Two short sentences with zero filler; the destructive scope is front-loaded and the consequence sentence follows immediately. Nothing could be cut without losing 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 destructive, single-parameter tool with no output schema, the description covers the resource, the cascade, and the widget impact, which is most of what an agent needs. The one meaningful omission is whether removal is permanent and whether widgets simply hide reviews or are otherwise altered.

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

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

Schema description coverage is 100%, and the schema itself explains that source_id comes from list_review_sources, so the description needn't repeat it. With a single fully documented required parameter, baseline 3 is appropriate.

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

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

States a specific verb and resource ('Removes a review source') and immediately clarifies scope with 'and all its reviews', which distinguishes it from delete_review (single review) and other remove_* siblings. It stops short of naming an alternative tool outright, so a 5 isn't warranted.

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 explicit when-to-use guidance: nothing says when to remove a source versus updating it, disconnecting the account, or removing single reviews. The only usage-adjacent signal is the implied consequence for widgets, which an agent must infer rather than being told.

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; the description adds genuine value by clarifying that updates are partial (only changed fields are sent) rather than wholesale replacement, and that the answer contains a join link. However, it says nothing about what happens on a name collision (the schema says names are unique), whether changes are reversible, or permission requirements — meaningful gaps for a destructive write.

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 clauses front-load the create-or-update decision, then add the observable outcome (join link, widgets). Nothing is padded, though the phrasing 'changes one when campaign_id is given' is slightly clunky.

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

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

For an 8-parameter upsert with no output schema, the description covers the mode switch, the partial-update rule, and what the caller receives (join link plus widget behavior). Remaining gaps — conflict handling on duplicate names and side effects of destructive changes — are secondary but real.

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

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

Schema description coverage is 100%, so every parameter already documents itself, including the campaign_id 'not sent = new campaign' semantics and the name/description requirements. The description's mention of campaign_id duplicates the schema, so the baseline 3 applies with no compensating detail.

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

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

The description uses a specific verb and resource ('Creates an Instagram hashtag campaign, or changes one') and explicitly states the branch condition (campaign_id present = update). This makes the create/upsert duality unmistakable and separates it from read/delete siblings like get_campaign or delete_campaign.

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

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

It clearly states the two usage modes and the key operational rule for updates: send only the fields to change. It lacks explicit routing guidance against siblings (e.g., when to use update_widget instead, or when to prefer list_campaigns first to obtain an id), but the context is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the concrete meaning of that destruction ('in place of its old tags', empty list removes them), the 20-tag ceiling, and the plan/widget eligibility gate. It does not cover failure modes (e.g. invalid post_id) or permission/auth details, so it stops short of a 5.

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

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

Front-loads the mutation and its replacement semantics in the first clause, then packs constraints into a short second half with no filler. The trailing 'Paid plans, Pro widgets that are not feeds' is a fragment but earns its place as an eligibility gate.

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 4-parameter mutation with a fully documented schema and no output schema, the description covers replacement behavior, limits, click semantics and plan gating. Only error/permission behavior is left unstated, which is minor given annotation coverage.

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

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

Schema description coverage is 100%, so url, x, y, description, image_clickable and the 20-item cap are all already documented. The description restates the tag structure and the click behavior rather than adding syntax, format or edge-case guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Sets the product tags (Shoppable links) of one post') and immediately clarifies the replace-not-append semantics. An agent knows exactly what the call does and that existing tags are overwritten, with no ambiguity against any sibling tool.

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

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

Gives clear applicability constraints — 'Paid plans, Pro widgets that are not feeds' — which tells the agent when the call is valid, plus the empty-list trick for removal. It stops short of naming an alternative tool or an explicit 'do not use when' condition, but no sibling offers equivalent tag functionality.

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 declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so safety is partly covered. The phrase 'They show in a minute or two' adds genuine value by signalling asynchronous, eventually-consistent behaviour after the call. However, it never clarifies whether this triggers an external Google/G2 fetch, whether it creates review records, or what quota or rate limits apply to an open-world call.

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

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

Two short sentences, front-loaded with the action and the source types, with no filler. The pronoun 'They' in the second sentence is slightly ambiguous, since it is unclear whether the reviews appear in the API response, in a widget, or in the dashboard.

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

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

For a one-parameter tool this is close to sufficient, but with no output schema the description should say what the call actually returns (reviews, a job status, or nothing) and how long to wait before re-reading. The asynchronous hint is present but not operationalised.

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

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

There is only one parameter and schema coverage is 100%, with the schema itself pointing at list_review_sources for the id. The description adds nothing beyond that, which is acceptable at this coverage level but not enriching.

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 ('Gets the new reviews') and resource ('a Google or G2 source'), so the agent can tell what it fetches. It does not, however, distinguish itself from the nearby get_review_source or import_reviews siblings, leaving the sync-versus-read-versus-import boundary to inference.

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 explicit statement about when to call this instead of get_review_source, list_review_sources, or import_reviews, nor any mention of prerequisites such as an already-connected account. The only implied guidance is that the source must exist, which is already in the schema.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that — that highlights can be cleared with [], that approved=true reveals a pending review, and that hidden=false re-shows it in widgets — but it never states whether fields omitted from the call are preserved or wiped, which is the key question for a destructive, idempotent update.

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

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

The purpose is front-loaded in three words, which is good, but the remainder is one long run-on sentence whose nested parenthetical '(author_name and body, and the others as add_review)' is hard to parse and forces the reader to consult another tool's definition. The 'Send one of these' list structure is helpful but the phrasing is loose rather than crisp.

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 16-parameter destructive mutation with no output schema, the description covers the what-to-send side reasonably but omits what happens to unspecified fields, whether review_id must reference an existing review, and what the caller gets back. Given the parameter count and destructive annotation, an agent still has material unanswered questions after reading it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns credit above baseline by grouping the 16 parameters into coherent update modes and clarifying the semantic relationship between 'approved' (pending-review visibility) and 'hidden' (widget visibility), which the individual schema strings do not make clear on their own. The mapping of author_name/body 'and the others as add_review' is a useful cross-reference for the manual-source field set.

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

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

The description states a specific verb-plus-resource ('Changes a review') and then enumerates the field groups that can be changed, which lets an agent distinguish this from add_review (which it names) and delete_review. It does not distinguish it from the sibling update_review_source, which operates on a similarly named but different resource, leaving some ambiguity about which 'update' to pick.

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

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

'Send one of these:' frames the description as a set of mutually exclusive usage modes (manual-source fields, highlights, approved, hidden), which is real usage guidance for how to call it. However, there is no guidance on when to use this tool versus add_review, update_review_source, or approve_pending_reviews, and no statement of prerequisites such as the review having to exist or belong to the account.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, so an agent knows this mutates state. The description usefully explains the runtime consequence of each setting, but it never addresses the destructiveHint=true implication — e.g. whether flipping auto approval on immediately publishes any reviews already sitting in the pending queue — nor does it mention permissions or reversibility.

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

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

Three short sentences, with the action stated first and the on/off consequences following immediately. Slight redundancy with the auto_approve schema description keeps it from a 5, but nothing is wasted.

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

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

For a two-parameter toggle with full schema coverage and no output schema, the description covers purpose and effect adequately. It stops short of explaining the side effects flagged by destructiveHint or what happens to already-pending reviews, which is the main thing an agent would want to know before flipping this switch.

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's 'On: new reviews show at once. Off: they wait for approval' largely restates the schema's own wording for auto_approve. The only added meaning is the constraint that the source must be Google or G2, which is useful but marginal; baseline 3 applies.

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

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

States a specific action and setting: turning auto approval on or off for a Google or G2 review source. That is clearly distinct from sync_review_source or remove_review_source, though the description never names a sibling to sharpen the distinction.

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

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

The on/off semantics imply the operational context (deciding whether incoming synced reviews publish immediately), but there is no explicit when-to-use guidance, no mention of prerequisites such as the source existing or being a Google/G2 type, and no pointer to get_review_source or list_review_sources for verifying state first.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds materially new behavior: partial-update semantics, all-or-nothing atomicity ("A refused call changes nothing"), delayed propagation ("shows a change within a few minutes"), replacement-not-merge semantics for accounts and review sources, and the coupling constraint that leaving a campaign requires accounts in the same call. The embed_code_changed caveat even explains the downstream human action required on the user's site, which is exactly the kind of consequence an agent would otherwise miss.

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

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

Front-loaded with the core action and the key rule ("send only what changes"), then organized by widget type, which is the right structure for a type-dependent tool. The middle enumeration of social-widget fields is a long, clause-heavy run-on sentence that takes effort to parse, but virtually every clause carries usable information rather than 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?

For a 7-parameter destructive mutation with a nested settings object and no output schema, the description covers the hard parts: partial updates, atomicity, per-type field applicability, list-replacement ordering, campaign coupling, and propagation delay. The only gap is the shape of the response beyond the mentioned embed_code_changed flag, which is a minor omission for an otherwise thorough definition.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it: it establishes that accounts and source_ids replace the entire current list in order, that the first account of a social widget's service supplies the header, that settings names come from get_widget and values from list_widget_types, and that campaign_id pairs with the "hashtag-campaign" filter_type. These are real semantic constraints the schema only hints at, though the ordering/header rule could be stated even more operationally.

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

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

Opens with a specific verb+resource ("Changes a widget") and immediately differentiates itself from create_widget/delete_widget/copy_widget by framing the operation as a partial update ("send only what changes"). It further disambiguates applicability by widget type (social vs review) and by which fields each type accepts, so an agent knows exactly what category of operation this is.

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

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

Gives clear operational guidance: send only changed fields, a refused call is a no-op, and the widget-type branching tells the agent when each parameter group applies. It also routes to sibling tools for prerequisite data (get_widget settings, list_widget_types for allowed values, list_accounts, list_review_sources, list_campaigns) and to get_embed_code for the post-update site step. It stops short of explicit when-not-to-use exclusions against copy_widget or update_review_source, which keeps it at 4.

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