skulayer

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

Goes well beyond the annotations: it discloses that validation and preview execute server-side, that the response bundles a match/change/exclusion report with per-field tallies, warnings and audit deltas, that the rule lands enabled and appended, and that it only takes effect on the next run. That is exactly the mutation behavior an agent needs and that readOnlyHint=false / destructiveHint=false does not convey.

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

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

Front-loaded with the action and its most consequential behavior, then packed with distinct operational facts (report contents, human review, warning meaning, enabled state, ordering, next-run timing). No sentence is filler and nothing is repeated.

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 three-parameter mutation with no output schema, the description covers what is created, what is returned, how the returned report should be handled, and when the rule takes effect. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% and all three parameters are documented there, so the schema carries the load. The description's only parameter-relevant content, that the definition is validated and uses the same format as preview_rule, largely repeats what the schema already says for the definition property. 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 ('Create a rule on a feed') and immediately bounds the scope: the definition is validated, a preview runs server-side, and the report comes back with the created rule. It is clearly distinguishable from preview_rule (no persistence) and delete_rule (removal) named among the 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?

Gives clear operating context: show the human the report, heed danger-level warnings, and know the rule applies on the next run rather than to the live feed. It also cross-references preview_rule for the definition format. It stops short of stating explicit exclusions such as 'use preview_rule first if you want to test without persisting', so no alternative-selection rule is spelled out.

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 beyond that: permanence, the reversibility workaround, and timing ('Takes effect on the next run'). It stops short of saying what happens if the rule id is unknown or whether the call is idempotent.

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, zero waste, with the destructive action and the safer alternative front-loaded. Every sentence carries distinct information: action, risk/alternative, timing.

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 delete with a fully documented schema and no output schema, this is nearly complete — the agent knows what it destroys, the alternative, and when it takes effect. Minor gaps: behavior on nonexistent ruleId and whether any return value confirms deletion.

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

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

Schema coverage is 100%, and both params (feedId, ruleId) are documented with sourcing hints (list_feeds, list_rules) in the schema itself. The description adds no syntax or format detail beyond 'by 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?

States a specific verb and resource with scope ('Delete one rule by id'), immediately telling the agent it operates on a single rule rather than a list or feed. The permanent-destruction framing distinguishes it from set_rule_enabled and from the read/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?

Explicitly names the alternative ('prefer set_rule_enabled with enabled=false') and the condition that selects it ('when the human might want the rule back'). This is a clear when-to-use-this vs when-to-use-that directive, not just implied context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely new behavioral context: summary counts are preview SAMPLE counts that must be compared to the sampled figure, and scheduled runs dominate newest events on hourly feeds. These caveats materially change how an agent would interpret results, though return format/pagination is not covered.

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 what an event contains, then usage, then caveats – a sensible order. It runs slightly long and the actor/action enumeration is dense, but nearly every sentence carries decision-relevant 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?

There is no output schema, so the description's enumeration of event fields (actor type, action verbs, feed, summary) is doing necessary work in telling the agent what it will get back. Combined with the sampling caveat, an agent has enough to call and interpret it, though exact response shape remains implicit.

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 baseline is 3. The description restates the actorTypes tradeoff (skip scheduled runs to see human/agent changes) but adds no syntax or ordering detail beyond what the schema already documents, and says nothing new about limit.

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

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

States a specific verb+resource ('the workspace's recent activity: who did what and when') and enumerates the event shape (actor, action, feed, summary), which makes the scope unambiguous. It does not explicitly distinguish itself from the sibling get_audit_findings, which is the most likely source of confusion.

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 concrete when-to-use guidance ('check what changed lately, or what you and others have already done, before acting again') plus a tactical instruction to pass actorTypes on hourly-feed workspaces. It stops short of naming an alternative tool and the condition that would select it.

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

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

Annotations already declare it read-only, non-destructive, and closed-world, but the description adds substantial behavioral context beyond them: it reports only the latest complete run, measures the post-rule delivered feed, and clarifies that opportunities sit outside totalIssues and the readiness score. That last point is exactly the kind of non-obvious trait structured fields cannot carry.

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 primary output is front-loaded in the first sentence, and the opportunities clarification follows. It is dense and slightly long, but nearly every clause conveys a distinct, useful fact; only minor tightening would improve it.

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

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

With no output schema present, the description must explain the return shape, and it does thoroughly: findings grouped by check with severity, counts, sample ids, explanatory guidance, plus the separate opportunities structure with counts and a rule definition. An agent has everything needed to call it and interpret results.

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

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

There is a single parameter with 100% schema description coverage ('Feed id from list_feeds.'), so the schema already carries the semantics. The description adds no additional detail about how feedId affects results, which is appropriate for the baseline when schema coverage is high.

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 ('audit findings for the latest complete run') and enumerates the returned structure: grouped by check with severity, counts, sample item ids, and guidance. It also distinguishes the opportunities payload as separate from defects, so an agent can tell it apart from siblings like get_merchant_issues or get_field_inventory.

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 context for use: it audits the DELIVERED feed (after rules) and the opportunities feed directly into preview_rule via a ready rule definition. However, it never explicitly states when to prefer this over sibling diagnostics such as get_merchant_issues or get_field_inventory, nor any exclusions.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, and the description still adds real behavior: archived feeds are resolvable and the response self-describes that state instead of erroring. It does not mention permissions or rate limits, but nothing here misleads.

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

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

Two sentences, front-loaded with the payload contents before the archived-feed edge case. The second sentence is a slightly dense run-on, but every clause carries information an agent would otherwise have to discover by failing.

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 characterize the return value — and it does, naming the three components returned. Combined with the archived-feed resolution behavior, nothing an agent needs to call this 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 feedId parameter is documented as coming from list_feeds, so the schema carries the semantics. The description adds only 'one feed' scope and no format or sourcing detail beyond that, which is the baseline-3 case for a fully documented single parameter.

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

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

Specific verb + resource ('Full detail for one feed') immediately followed by an enumeration of what that detail contains: configuration, latest complete run summary, and rule-stack size. The singular 'one feed' plus the sibling name list_feeds in the schema makes the list-vs-single distinction obvious.

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 context for a non-obvious case: archived feeds resolve and say so, so a stale id from an earlier conversation yields an explanation rather than a not-found. It stops short of naming alternatives (e.g. list_feeds for discovery, get_run_status for run detail), so routing against siblings is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered; the description adds substantive content beyond that by spelling out what the response contains (per-field item counts, custom vs. shopping attribute classification, before/after coverage). It stops short of noting result size, pagination, or cost of the call, 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?

The payload is front-loaded with the core definition before the sibling routing, and nearly every clause adds information an agent needs. It is dense and runs long for a one-parameter read tool, with the triad framing consuming part of the space, but there is little outright 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 carries the burden of describing return values and does so concretely: per-field value counts, attribute classification, empty-row detection, and before/after coverage. What is missing is anything about result size, ordering, or whether coverage numbers are per-feed or per-attribute aggregate in practice.

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 feedId is documented there ('Feed id from list_feeds'), so the baseline is 3. The description adds no additional meaning about feedId, such as whether the inventory is scoped to the latest run or a snapshot, so it does not exceed the baseline.

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

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

States a specific resource (the merchant's source feed field inventory) and exactly what it reports: per-field presence, recognition status, empty-on-every-row detection, and coverage before/after the rule stack. It explicitly positions itself against siblings get_audit_findings and get_merchant_issues, so an agent can distinguish it without opening the schema.

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

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

Gives an explicit ordering instruction ('Use it BEFORE proposing rules') and names the two alternative diagnosis tools with the axis that separates them (merchant sent vs. SKULayer thinks vs. Google thinks). It also states the distinguishing question only this tool can answer: never-sent vs. sent-blank vs. unusable-value.

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 useful context beyond them: the three lifecycle states including what 'fix_shipped' actually means, coverage of account-level issues, and the latest-pull scan summary. However, it says nothing about staleness/freshness of the pull, rate limits, or whether a re-scan is triggered — gaps that matter for a tool whose value hinges on how current Google's verdict is.

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 payload and the sibling contrast in the first two clauses; every sentence carries information (return shape, lifecycle semantics, prerequisite, workflow hand-off). It is dense but the long single paragraph with an embedded parenthetical and an em-dash chain makes it slightly harder to scan than it needs to 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?

No output schema exists, so the description carries the return-value burden and does so thoroughly — item shape, lifecycle states, account-level issues, and a scan summary. Combined with the prerequisite and the follow-up workflow, an agent has everything needed to decide and call correctly.

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

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

Single parameter with 100% schema coverage and a description that already points at list_feeds, so the schema does the heavy lifting. The description adds only the connection prerequisite, not any feedId format or failure-mode detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Google's OWN verdict on a feed... per-issue-code cases with severity, affected-item counts, sample ids') and explicitly contrasts itself with get_audit_findings. An agent can tell instantly what this returns and how it differs from the audit 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?

Names the alternative ('the audit is what SKULayer thinks, this is what Google thinks'), states a hard prerequisite ('requires the feed to be connected'), and routes the follow-up workflow ('fixes are built like any rule — preview_rule then create_rule'). When-to-use, when-not, and next step are all explicit.

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

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

Although annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, the description adds substantial behavioral context: it explains the status lifecycle, what accounts and connections contain, and explicitly states that tokens and the consent URL are not returned.

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 front-loads the main purpose, then explains returned fields and the pending-status routing condition. Every sentence carries operational meaning, and the final exclusion about tokens and consent URL is a useful boundary statement.

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

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

With no input parameters and no output schema, the description does the necessary work by explaining the status values, account and connection contents, the pending decision state, and what is not returned. It is complete for an agent deciding whether and how to call this tool.

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

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

The tool has zero parameters, so there are no input parameters to document beyond the baseline. The description does mention connectionId, accountId, and feedId, but only in the context of the alternative select_merchant_account tool, not as parameters of this tool.

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

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

The description uses a specific verb-resource pair ('Read this workspace's Merchant Center link') and clearly distinguishes the tool from siblings like start_merchant_link and select_merchant_account. It also defines the status values and returned collections, so an agent can immediately understand what this tool does.

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

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

It gives an explicit conditional routing rule: when status is pending and accounts has more than one entry, the agent should call select_merchant_account with connectionId, accountId, and feedId. This directly names the alternative and the condition that selects it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond that: the full status enum, what error information surfaces on failure, and the polling pattern, which matters for how an agent should call it repeatedly.

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

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

Two sentences, no filler. The payload description comes first and the usage instruction second, which is the right ordering for an agent scanning the definition.

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 returns, and it does so thoroughly (status values, counts, timing, error text). The absence of guidance on polling cadence or whether repeated polling incurs cost keeps this just short of complete.

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

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

Schema description coverage is 100% and both parameters already document their source ('Run id from trigger_run or list_feeds', 'Feed id from list_feeds'). The description adds nothing about parameters, so the baseline 3 applies.

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

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

States the specific resource (one run) and exactly what it returns: progress, outcome, status values, item counts, audit issue count, timing, and error message. That level of detail distinguishes it clearly from trigger_run and the other read 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?

"Use after trigger_run to poll to completion" gives concrete situational guidance and names the companion tool. It doesn't spell out any exclusions, such as which tool to use for listing all runs or for feed-level status.

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

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

Beyond the readOnly/non-destructive annotations, it discloses that archived feeds are excluded because they do not run or serve, and that only a person can restore one in the app. That is meaningful behavioral context for an agent deciding what this tool can and cannot surface.

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

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

Three tight sentences: the return contents are front-loaded, then the discovery cue, then the archived exclusion. Every sentence earns its place.

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

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

No output schema exists, so the description lists the important returned fields including latest run and audit issue count. It also covers the key exclusion and the restoration limitation, making it complete for a zero-param discovery tool.

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

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

The tool has zero parameters, so there are no parameter semantics to explain; the baseline for a zero-param tool is 4. The description appropriately focuses on result content instead.

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

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

States a specific verb and resource ('List every live feed') with workspace scope, and enumerates the returned fields. An agent can distinguish this broad inventory from the detail-oriented sibling get_feed.

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?

'Start here to find feed ids' clearly signals the initial discovery use case, and the archived-feeds note explains an important exclusion. It does not explicitly name get_feed as the alternative for inspecting a single feed, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return shape — execution order, enabled state, plain-English summary, and full JSON definition — which is exactly the behavioral context an agent needs.

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 with zero filler, and the most important fact — that rules come back in execution order — is stated up front. Every clause conveys distinct information about the response.

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 list tool with full schema coverage and annotations covering safety, the description supplies the missing piece — the composition of the returned items — which compensates for having no output schema. Only the lack of sibling routing guidance keeps it from being fully complete.

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

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

There is a single parameter with 100% schema description coverage ('Feed id from list_feeds'), so the schema already carries the semantics. The description only implies feed scoping through 'The feed's rule stack' and adds no format or sourcing detail 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 names the resource precisely ('the feed's rule stack') and enumerates what each entry contains — name, enabled state, summary, full JSON definition — so an agent knows exactly what comes back. It doesn't explicitly contrast itself with siblings like preview_rule or set_rule_enabled, but the read/list nature 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?

Usage is only implied: the description makes clear this is for inspecting a feed's rules, which naturally routes an agent away from create_rule/delete_rule. However, it never states when to prefer this over preview_rule or get_feed, nor any prerequisites beyond the schema's 'Feed id from list_feeds' 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?

The key disclosure is 'NOTHING is saved', which is exactly what an agent needs given readOnlyHint=false and destructiveHint=false — it prevents mistaking this for a persisting mutation. It also explains the deterministic-first, then AI matching order and that AI is only used when available and useAi is not false. Minor gap: it does not say how many AI calls or how large a mapping table to expect.

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

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

Purpose and the no-save constraint are front-loaded, with options collected at the end after 'Options:'. The middle sentence is very dense with parentheses and nested clauses, which slightly hurts skimmability, but 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 still tells the agent what comes back (a mapping table plus a ready-to-save rule definition keyed on productType) and what to do next. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds interaction semantics the schema states separately: onlyMissing scopes the rule to items with no category yet, and defaultCategory applies to productTypes absent from the table. It also clarifies the useAi fallback ordering.

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 (propose a googleProductCategory mapping) and resource (feed items grouped by productType), and names both the matching strategy and the output artifact. It is clearly distinguishable from siblings like create_rule (persists) and search_taxonomy (resolves individual paths).

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 an explicit end-to-end workflow: show the human the mapping, resolve unmatched types with search_taxonomy, then save with create_rule which runs preview and returns the impact report. It also names the condition for scoping (onlyMissing=true) versus the default behavior of fixing wrong existing values.

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

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

The description adds substantial behavioral detail beyond the annotations, including match/change/exclusion counts, per-field tallies, danger warnings, audit deltas, and before/after diffs. It also reinforces the non-mutating behavior and explains how group exclusions appear in preview warnings.

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

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

The description is front-loaded with preview behavior and safety, then transitions into a dense but necessary DSL reference. It is long, but for a complex rule format the detail largely earns its place.

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

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

Given the nested definition object, no output schema, and complex rule DSL, the description is complete enough to support correct invocation. It explains return metrics and the rule format in enough detail that an agent can both choose and call the tool.

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

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

Although schema coverage is 100%, the schema only says definition is an object; the description provides extensive semantics for the rule definition format, condition operators, action types, and variant-group handling. This is exactly the context an agent needs to construct a valid definition.

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: preview an UNSAVED rule against a sample of the latest run. It clearly scopes the operation and distinguishes previewing from saving or listing rules through the emphasis on UNSAVED and 'Nothing is written anywhere.'

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

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

It gives a clear usage context: previewing unsaved rules against the latest run sample, which implies checking before saving. However, it does not explicitly name create_rule as the save alternative or state when not to use the tool.

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

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

Annotations already establish a safe read, so the description adds real behavioral context: only the latest complete run is searchable, delivered (post-rules) is the default surface while base shows ingested data, and matching is case-insensitive. It stops short of mentioning the hard limit of 25 items per call or what happens with an incomplete/latest run absent.

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

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

Three tight sentences, front-loaded with the primary action and default behavior, then matching semantics. Every clause carries information not already obvious from the name.

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

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

For a five-parameter, read-only, paged search with a fully documented schema and no output schema, the description covers scope, default view, and matching rules — everything an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding that the query match is case-insensitive across id, title, brand and product type, and by restating view semantics in prose. offset and limit behavior is left entirely to the schema.

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

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

States a specific verb (search/page) and a precisely scoped resource: items of the latest complete run. The scope qualifier 'latest complete run' clearly separates it from run-level siblings like get_run_status and from feed-level siblings like get_feed.

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 implies two modes (search with query vs. page through everything) and clarifies the default view, but never says when to pick this over a sibling such as get_field_inventory or when the tool is inappropriate (e.g., historical runs are unreachable). No alternatives are named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavior — ranked category paths with numeric ids and a flag for whether the query is itself a valid category. It stops short of describing ranking criteria or what an empty result means.

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, both loaded: the first defines the resource and the return shape, the second enumerates use cases. No filler, and the highest-value information (what it searches, what it returns) comes first.

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 return-value disclosure and does so (paths, numeric ids, validity flag). Combined with a 100%-documented two-param schema and clear annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds the useful semantic that the query may legitimately be a free-text term, a full path, or an id, and that a valid path/id short-circuits into a validity check rather than a search. The limit parameter is left entirely to the schema.

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

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

States a specific verb and resource ('Search Google's product taxonomy') and immediately defines the resource as 'the set of valid googleProductCategory values', which separates it from sibling map_categories without the agent 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 three concrete selecting conditions: finding the right category for a product type, fixing unmatched entries from map_categories, and validating a value before writing it into a rule. The map_categories reference explicitly routes the agent between the two 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 mark this as non-read-only, non-destructive, and closed-world. The description adds important context: Owner-only access, the account must be one Google actually showed, and it does not write a feed or data source to Google. It does not describe persistence or reversibility, but the added constraints are meaningful.

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 short and front-loaded, with each sentence adding useful trigger, parameter-source, validation, permission, or scope information. 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?

For a three-parameter local selection tool with full schema coverage and annotations, it supplies the trigger, required ID sources, authorization restriction, account validation, and non-write scope. No output schema exists, so return-value explanation is not required.

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

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

Schema coverage is 100%, so the schema already defines all three parameters. The description still adds value by linking connectionId and accountId to get_merchant_link and adding the validation constraint that the account must be one Google showed for the connection.

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

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

The description states a specific action and resource: choosing which Merchant Center account a feed uses. It also ties the tool to get_merchant_link, making it distinguishable from siblings like listing links or starting a 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?

It gives an explicit trigger: required when get_merchant_link lists more than one account, and the IDs must come from that result. It does not explicitly name alternatives or state the one-account case, so it falls short of full when/when-not/alternative 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?

Adds real value beyond annotations: the effect is deferred ('from the next run onward') and state is preserved ('nothing else about it changes'). Annotations only declare non-readOnly/non-destructive; the temporal and reversibility detail comes from the description. No mention of auth or idempotency of repeat calls.

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

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

Three short sentences, front-loaded with the action, then the key behavior, then the id-discovery hint. Nothing 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?

For a three-param mutation with full schema coverage and annotations covering safety, the description supplies the effect timing and state-preservation semantics that the structured fields lack. It does not say what is returned or whether the call is idempotent, a minor omission.

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 all three params are documented there, including the boolean semantics of enabled and the list_rules source for ruleId. The description adds only 'by id' and repeats the list_rules pointer, 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 pair and resource ('enable or disable one rule by id') and immediately scopes the effect ('nothing else about it changes'), which distinguishes it from delete_rule. An agent can pick it out from siblings 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?

Points to list_rules for id discovery and implicitly contrasts with destructive removal by saying nothing else changes. It stops short of an explicit 'use this instead of delete_rule when you want to keep the rule' sentence, so it is clear context but not 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 only say readOnly=false, destructive=false, openWorld=false; the description goes much further by disclosing the return artifact (a short-lived, single-use SKULayer URL), the identity requirement (owner signed in as the same person), the token boundary ("You never receive Google tokens"), and the rate limit. It also clarifies the side-effect boundary — no data source added, no writes to Merchant Center — which is not inferable from the non-destructive annotation alone.

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

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

Front-loads the action and the returned URL, then layers the conditional feedId path, the multi-account fallback, and the hard constraints in descending order of importance. Dense but every sentence carries distinct operational information; nothing is repeated from the schema or annotations.

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, and the description compensates fully by describing the returned URL and its single-use, short-lived nature plus the redirect to Google consent. For a single optional parameter with a follow-up flow, an agent has everything needed to call it and to handle both the one-account and many-account outcomes.

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 real semantics by explaining the conditional nature of feedId (attaches the feed only when Google shows exactly one account) and describing the branch when multiple accounts exist. The schema already covers the omit case, so the marginal gain is modest rather than transformative.

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 ("Start connecting Google Merchant Center for this workspace") and immediately distinguishes the tool from siblings by naming get_merchant_link and select_merchant_account as the follow-up path. It also carves out explicit non-scope ("does not add a data source and does not write to Merchant Center"), so the agent can tell exactly what this call achieves.

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

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

Gives a clear when-to-use and a full branch plan: owner-only initiation, poll get_merchant_link and call select_merchant_account when several accounts appear. Constraints are explicit (owner only, 5 starts per workspace per hour on top of the normal MCP limit), which is exactly the routing information an agent needs before invoking.

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

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

Beyond the destructiveHint=true annotation, it discloses the auth scope required, rate/quota constraints, per-feed concurrency, the return value (runId), and the follow-up polling pattern. The line "An in-flight run never affects the live delivered feed" importantly scopes how far the destructive hint reaches, which the annotations alone cannot convey.

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 ordered by importance: what it does, what it requires, what it returns, what to do next. Every sentence carries distinct information with no repetition of the schema or annotations.

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

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

For a single-parameter mutation with no output schema, the description covers the operation, preconditions, return value, and the exact next call. There is nothing an agent needs in order to call this correctly that 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 feedId parameter is already documented as coming from list_feeds, so the schema does all the work here. The description adds no format, example, or constraint on feedId, which is the expected baseline 3 when one fully-described parameter exists.

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

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

It gives a specific verb and resource ("Start a feed run") and then enumerates the pipeline it performs: fetch source, apply rules, audit output, compile channel files. That detail distinguishes it from the read-only siblings such as get_run_status and preview_rule 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?

It states the prerequisites (write-scoped connection, workspace SKU limit, manual-run cap, one run at a time per feed) and routes the agent onward to get_run_status for completion polling. It never explains a when-not case or names a competing tool to use instead, but no sibling also triggers runs, so the relevant guidance is largely present.

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