WisePPC

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful catalog semantics and listing behavior, but does not describe return format, pagination, or other operational details beyond what annotations provide.

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

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

The description is front-loaded with the core purpose and then efficiently enumerates each kind. It is dense but largely waste-free, though the single long sentence with semicolon-separated clauses is somewhat run-on.

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 meta-tool with no output schema, the description covers the main kinds, listing behavior, and key parameter usage. It is complete enough for an agent to call correctly, with only minor gaps around return shape and defaults.

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 description adds meaning beyond the schema by explaining the kind values, when to omit id, and how expand/detail and category apply to specific kinds. Schema coverage is 67%, and the description compensates well for the most important parameters, though it does not fully document every parameter nuance.

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 this as a catalog for the other tools and enumerates the five supported kinds, so an agent can understand its role. It is specific about the resources covered, though it uses a noun phrase rather than a crisp verb and relies on 'other tools' for sibling differentiation.

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

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

It explains what each kind provides and implies usage contexts, such as tables being a run_query guide and operations covering submit_mutation request schemas. It also states 'Omit id to list,' but does not explicitly name when not to use this tool or compare it directly with 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 cover readOnly, idempotent, non-destructive, closed-world behavior, and the description adds real value on top: default 'all states unless filtered', stale assets omitted unless include_stale, only newest asset version by default, DRAFT widgets for brand_store_page, and money returned in the profile's native currency. These defaults are the sort of behavior an agent could not infer from the schema, though return shape details remain thin for some entities.

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 telegraphic and dense but well front-loaded: each clause opens with the entity name it governs, so an agent can scan to the relevant segment. The brace-and-pipe notation for Ads v1 objects is cryptically compressed, but it is concise with essentially 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 32-parameter polymorphic read tool with no output schema, the description carries the return-shape burden and does so per entity (object envelope with nextToken for Ads v1 objects, columns/rows for campaign_settings, config+performance+search terms for campaign_details). A few entity/parameter interactions (pagination via idOffset, id filtering on ads/targets) remain unstated, so it stops short of completely self-contained.

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 84% schema coverage the baseline is 3, and the description earns a bump by mapping parameters to entities: negative=true for negative targets, ids for assets/campaign_details/brand_store_page, entity-specific states, and path+widgetTag linkage to ads.brand_store.update_page_asins. Some params (ad_group_ids, campaign_ids, nextToken, idOffset) are left to the schema, so it is not exhaustive.

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 enumerates every entity value (campaigns, ad_groups, ads, targets, portfolios, assets, campaign_settings, campaign_details, brand_store_page) and states what each returns, so an agent can tell which read it gets. The verb is only implied ('get'/'Read'), and nothing distinguishes it from siblings like query or run_query, which keeps it from 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?

'Read before/after submit_mutation' is the only explicit usage directive, and it correctly frames this as a read-before-write/verify tool. There is no guidance on when to prefer get_entities over query, run_query, or get_report, and no stated preconditions, so usage is implied rather than 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?

Adds substantial behavior beyond the annotations: 'A mutation executed status means executor acceptance, not proof of entity reconciliation', 'nextCursor repeats the same filters; since applies to the first page only', and the prompt-injection warning that event text is untrusted data. These are exactly the traps an agent would otherwise fall into.

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?

Very tight for the amount of information packed in — the scoping constraint leads, then routing, then semantics, then the safety caveat. The telegraphic semicolon style is dense but every clause is load-bearing and no sentence 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?

For an 8-parameter read tool with no output schema, the description covers access requirements, parameter routing, pagination semantics, and data-trust caveats. The one gap is that it never characterizes what an event record looks like on return, which matters somewhat given there is no output schema to fall back on.

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 only 50% schema description coverage, the description carries real weight: it defines the mutationId vs sellerId+marketplaceId mutual exclusion, marks subjectId as optional exact SKU/ASIN, and explains cursor and since scoping. It doesn't cover limit's range/default, which the schema does, so this is compensation well done but not exhaustive.

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

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

The opening ('Up to 30d authorized history') plus the closing 'This is a history read, not a subscription' make clear this retrieves historical events. The verb is implicit rather than stated outright — it relies on the annotations title 'Read event history' — and it never distinguishes itself from the sibling get_history, which is the closest alternative.

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?

Strong conditional routing: 'mutation.*: mutationId (own); no sellerId/marketplaceId/subjectId. Else sellerId+marketplaceId; optional subjectId' tells the agent exactly which parameter shapes apply to which event families. It also rules out a misuse ('not a subscription'). What's missing is any guidance on when to pick this over get_history or get_mutations.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses concrete behavioral traits: results are newest-first, values are untruncated, an asin must belong to your own listings, and 'History may start after creation' plus 'no lifecycle deletions yet' set data-coverage expectations. These are non-obvious constraints that materially affect interpretation of results.

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?

Dense but front-loaded — the core action and result shape come first, then per-mode caveats. The telegraphic style ('sku: one seller listing...') is efficient, though it borders on shorthand that requires careful parsing.

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

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

For a 10-parameter, no-output-schema read tool, the description covers return ordering, value fidelity, data coverage limits, and permission requirements per mode — enough to call and interpret it correctly. The main gap is that categories and changeTypes filter semantics are undocumented anywhere.

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 40%, so some compensation is warranted. The description does clarify the sku and asin parameters and their scope, but it is silent on categories, changeTypes, pageSize, and pageToken, and adds little beyond the schema for from/to/fields. Partial coverage of the 10 parameters keeps this at baseline-plus.

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+resource — 'Field changes WisePPC observed' — plus ordering ('newest first') and payload shape ('old/new values untruncated'). It distinguishes the two lookup modes (sku vs asin) but does not differentiate itself from closely related siblings like get_events or get_mutations.

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

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

It gives useful mode-selection guidance: sku for one seller listing on an amazon_sp target, asin for one catalog item that must belong to your listings. Permissions are named per mode. However, there is no explicit when-to-use or when-not-to-use guidance relative to sibling history/event tools, so alternatives are left 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?

Beyond the read-only and idempotent annotations, the description discloses important behavior: order_detail stores raw rows by block with exact money strings and section/offset paging, aplus_content comes from a copy polled about daily, and estimate_fees returns live estimates that are not guarantees and are cached for six hours.

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 dense but front-loads the overall purpose and then groups details by resource, with every phrase carrying useful information. It loses a point for being a single semicolon-heavy paragraph that is less scannable than it could 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 23-parameter multiplexer with four resources, the description covers all modes and important quirks such as paging, freshness, caching, and estimate reliability. It does not describe the return envelope or some output shapes, but the rich schema and annotations cover much of that 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 96%, so the schema already documents nearly every parameter. The description still adds cross-parameter meaning by explaining section plus offset paging for order_detail, the estimate_fees action default and item limit, and the caching behavior tied to that resource.

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 Amazon seller-marketplace data retrieval tool and enumerates four resource modes with concrete contents. It is clear what the tool returns, though it does not explicitly distinguish itself from the generic sibling tools.

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

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

The per-resource descriptions imply when each mode is useful, such as order_detail for stored order rows and estimate_fees for live fee quotes. However, there is no explicit guidance on when to use this tool versus alternatives like query or get_report, and no exclusions are stated.

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

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

Beyond the annotations, the description discloses pagination via `next_cursor`, byte-slice behavior, compact-list behavior, long-poll limits, timeout semantics, and legacy read-only history. These operational details materially help an agent understand how the call behaves.

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

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

The description is compact and front-loads the core purpose, with no wasted sentences. However, it is a dense semicolon-heavy block, which reduces readability despite being concise.

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

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

For a 13-parameter query tool with no output schema, the description covers the main retrieval modes, return-style distinctions, pagination, long-poll behavior, and legacy-source constraints. It is largely complete, though it leaves some filter and output-detail gaps for the schema and agent inference.

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 69% schema coverage, the description adds important meaning for `mutationId`, `cursor`, `mineOnly`, `waitSeconds`, and `source=legacy` that the schema alone only partially conveys. It does not explain every filter such as `batchId`, `verbose`, or `status` values, so the schema still carries some weight.

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-resource pair, mutation status, and immediately names the sibling action it reports on (`submit_mutation`). It also distinguishes the main retrieval modes: single mutation, list, byte slices, long-poll, and legacy history.

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 clear mode-selection guidance: `mutationId` for one change, no id for a compact list, `mineOnly=true` for the caller's rows, `waitSeconds` for long-polling, and `source=legacy` for read-only history. It does not explicitly name alternatives such as `get_events` or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds two genuinely new behavioral facts: a personal-data opt-in is required, and every request is access-logged (an audit consequence an agent should know before calling). It also discloses the specific PII returned per record type, which is above the annotation bar, though it says nothing about empty-result or not-opted-in failure behavior.

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

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

The purpose is front-loaded in the first clause, but the body is one long run-on sentence with dense nested parentheses and semicolons that takes effort to parse. Every clause carries information, yet the structure works against quick scanning.

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 15-parameter PII tool with no output schema, the description covers the essentials an agent needs: the opt-in gate, audit logging, and what each record type returns. Remaining gaps are pagination behavior across many filters and the meaning of pii_cleared, but those are handled in the schema.

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

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

With 93% schema description coverage the schema already documents nearly every parameter, so the baseline is 3. The description contributes the record-dependent meaning (orders joins on ebay_orders.order_id and yields buyer/ship-to PII; messages returns list-with-snippet vs full thread ordered oldest-first), but leaves limit/cursor, window_days, country_codes, fulfillment_status and pii_cleared 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 resource and scope: personal data of the seller's *own* buyers and customers, keyed by target and record, then enumerates the eBay record types (orders, messages) with the fields each returns. This is clearly distinguishable from get_marketplace_data, though the description never names that sibling explicitly to draw the contrast.

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

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

Gives a prerequisite (needs the personal-data opt-in) and an implicit branch rule: omit conversation_id for the messages list, pass one for a full thread. It does not say when to prefer this over get_marketplace_data, get_entities, or get_events, so the agent must infer the boundary from the resource names alone.

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 readOnly/openWorld=false/idempotent/non-destructive, so the safety profile is covered; the description still adds real value by stating money is returned in the profile's native currency and that attribution_link reads enrolment status rather than enrolling. Return-field disclosure compensates for the absent output schema.

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

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

Every clause carries information and the highest-value mode (health_check) is front-loaded, with no filler sentences. The heavy semicolon-and-parenthesis packing makes it denser than ideal for one-pass reading, which keeps it off a 5.

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 20-parameter, single-required-param tool with no output schema, the description covers what each report returns, its currency, and its side-effect boundaries. Remaining gaps are minor: pagination semantics and the default/max row behavior are left entirely to the schema.

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

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

Schema description coverage is 95%, so the baseline is 3 and the schema already documents per-report applicability for asin, limit, format, dates and filters. The description adds only a little beyond that, chiefly what omission of asin means for attribution_link; it says nothing extra about target, columns or sortBy defaults beyond what the schema states.

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?

Each of the four report modes is described with a specific verb/resource pair and concrete payload (e.g. product_performance returns 'spend, sales, ACOS, ROAS, CTR, CPC, conversion rate'), which clearly separates it from siblings like query or run_query. It falls short of 5 only because there is no single lead sentence stating what the tool itself is, leaving the agent to infer the dispatch pattern from the 'report:' prefixes.

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 given per mode with in-line questions ('what needs attention?', 'missed opportunities') and an explicit negative constraint on attribution_link ('does not enrol'). No alternatives among siblings are named and no when-not-to-use is stated, so it stops short of the top band.

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, idempotent, non-destructive, closed-world), and the description adds genuine behavioral context: it returns 'changes since your last session' and a target primer with pending actions, runbooks, and gotchas. That disclosure of what the call yields goes beyond the annotations, though it does not discuss pagination behavior or response shape granularly.

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 tightly front-loaded with 'Start here; no arguments' and then a compact enumeration keyed by selector. A few terms ('key_grants', 'tool-surface version') are cryptic jargon that cost a little clarity, but overall 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?

For an 8-parameter, zero-required orientation tool with no output schema, the description effectively conveys the return structure by enumerating what overview, target, and each section provide. It leaves fine-grained detail (paging mechanics, exact response fields) to the schema, which is acceptable given no output schema but keeps it from a 5.

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 already 100%, so the baseline is 3, but the description adds meaning beyond the enum labels: target is 'kind:account[:unit]' and represents a profile primer, grants returns each unit's write ops and modes, accounts is 'all, paged'. It stops short of explaining limit/offset/category/destinationId explicitly, relying on the schema for those.

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 tool is clearly the entry-point/orientation tool ('Start here; no arguments') and it enumerates the concrete resources it surfaces: business, connected accounts with target ids, grants, preferences, and tool-surface version. It reads as a session-context loader rather than restating the name. It never differentiates itself explicitly from siblings, keeping it from 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?

'Start here' is a strong, explicit first-use directive, and the per-selector notes (target, section) tell an agent how to route once inside. There is no explicit statement of when NOT to use it or a named sibling alternative, which caps it below 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that: the server validates targets against the account and a rejected request returns the legal vocabulary, which tells the agent how to recover from errors. It does not describe result volume or cost characteristics, keeping it 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-loaded with the core purpose and the run_query distinction, and every subsequent sentence carries operational content (metric types, dimension vs segment, filters vs having, target routing). The density of backticked terms makes it feel compressed, but little 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 15-parameter tool with nested objects and no output schema, the definition covers the hard parts: where ids come from, what the server does (writes SQL), target selection per domain, aggregation order, and error recovery. Remaining gaps — row shape and the interaction of sort/limit/offset with compare output — are mostly handled by the schema's own parameter descriptions.

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 descriptions for filters, having, dimensions, compare and granularity already carry their own semantics ("Pre-aggregation filter on dimensions", "Each segment fans rows"). The description exceeds baseline mainly by explaining metric arithmetic — additive sums vs ratio-of-sums rather than average-of-ratios — which the schema only gestures at with "(additive or ratio)".

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 ("Structured analytics query on a catalog dataset") and immediately scopes it against the sibling: "the server writes the SQL (curated path; SEPARATE from run_query's raw SQL)". An agent can distinguish this from run_query without opening either schema.

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

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

Gives clear routing: ids come from describe(kind='datasets'), target selection is mapped per domain (seller→amazon_sp, ads→amazon_ads, ebay→ebay). The run_query separation implies when to prefer the curated path, but there is no explicit "do not use when" statement or guidance on choosing between datasets.

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 a non-destructive, non-idempotent, closed-world write. The description adds useful return information (id, time, status) but does not warn that non-idempotent submission means repeated calls create duplicate tickets, nor mention any auth or rate constraints.

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 and recipient, then the triggering condition, then the return value. 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?

There is no output schema, and the description compensates by naming the returned fields (id, time, status). The only shortfall is the unmentioned duplicate-submission behavior for a non-idempotent write, which an agent might reasonably need.

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 enums for category and severity, so the schema fully documents the five parameters. The description adds nothing about field meaning, which is acceptable at baseline but not value-adding.

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?

A specific verb ('Report') plus the resource ('a problem, missing data, an unclear error or an idea') and the recipient ('the WisePPC team'). The enumerated cases make the tool unmistakable against query-oriented siblings like run_query or get_report.

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

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

Explicit invocation conditions are given: 'when a tool answer is wrong, empty without a reason or confusing.' It doesn't state when not to use it or name an alternative channel, but none of the siblings overlap, so 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 readOnlyHint/idempotentHint/non-destructive, and the description adds real operational context beyond them: LIMIT defaults and caps per credential tier (100/500, 500/5,000, 1,000/50,000), silent clamping rather than rejection, a byte budget on responses, server-injected predicate columns, and that nullIf is blocked while `if(x=0,null,x)` is the sanctioned ratio form. These are non-obvious constraints an agent could not infer from annotations or schema.

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

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

Front-loaded with the capability and table list, then ordered into date-bound rules, granularity, injection rules, and limit tiers — a sensible progression. It is dense but nearly every clause is load-bearing; only the granularity enumeration (time_window_month 1-12, week number without year, bucket functions) runs a little long relative to the rest.

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 complex, no-output-schema SQL tool this covers the essentials an agent needs to call it correctly: table inventory, mandatory date-bound rules, granularity semantics, reserved columns, ratio-expression restrictions, and result-size limits. Remaining gaps are minor — no guidance on malformed-SQL error behavior and no explicit deferral pattern to the sibling 'query' tool.

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

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

Schema coverage is already 83%, so the baseline is 3; the description still adds value by explaining that max_rows values larger than the tier cap are clamped silently rather than erroring, and that money values are in the profile's native currency resolvable via get_session_context. It does not add anything for `target` or `columns`, but the schema handles those adequately.

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

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

The description opens with a specific verb+resource ('Raw SELECT SQL against analytics tables (ClickHouse)') and enumerates the exact tables available, so the agent knows precisely what it does. It also implicitly routes schema discovery to describe(kind='tables'). It does not, however, distinguish this from the sibling tool 'query', leaving the agent to guess which query entry point to use.

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?

Strong conditional guidance: it states that every time-series scan needs a literal lower date bound (naming time_window_date and changed_at), that product_catalog is exempt, and that business_profile_id/profile_id must not appear in WHERE clauses. What is missing is explicit when-to-use-this-vs-'query' routing and any statement about when to prefer get_report or get_events instead of raw SQL.

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 write (readOnlyHint=false), destructiveHint=true, and idempotentHint=true. The description adds real behavioral context beyond that: preferences persist and are 'applied in later sessions', value=null deletes the key, value is capped at 500 chars. It doesn't describe the response body or what happens on partial/invalid input, keeping it out of 5 territory.

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 is tight and front-loaded around the preferences semantics, but the closing fragment ('key tracked_search_terms + marketplaceId, searchTerms: value track') is garbled text that costs clarity without conveying a complete thought.

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 6-parameter write tool with no output schema and annotations covering the safety profile, the description covers the main mutation and deletion semantics adequately, but leaves the tracked_search_terms workflow (a key plus marketplaceId plus a terms array) unexplained and says nothing about success/failure behavior.

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

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

Schema coverage is 67%, so the schema already documents key, value, searchTerms, and marketplaceId; the description adds value over that only by clarifying that value=null removes the preference and by glossing categories ('targets (business goals)'). The final clause about tracked_search_terms, marketplaceId, and searchTerms is grammatically broken and fails to explain how those parameters combine, which is exactly the gap the schema leaves open.

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

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

The opening sentence states a specific verb and resource ('saves business profile data') and the following clauses define the 'preferences' section as saving a standing rule applied in later sessions, so the agent can tell this is a write/persistence tool distinct from read siblings like get_entities or query. It stops short of naming any sibling or contrasting with submit_mutation, and the trailing fragment ('key tracked_search_terms + marketplaceId, searchTerms: value track') muddies rather than sharpens purpose.

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

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

The phrase 'Saves a standing rule the user stated for this account' implies the trigger context (persisting user-stated preferences across sessions), which is useful implied usage. But there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as submit_mutation or describe for other profile operations.

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

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

Annotations already flag destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is carried structurally. The description adds two things beyond that: the review-versus-direct-execution path chosen by the key's grants, and that it returns a mutation id (valuable since there is no output schema). It leaves notable gaps, though — it never explains what the required idempotencyKey guarantees given idempotentHint=false, nor what happens on partial failure of a batch.

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

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

Five short, front-loaded sentences with no filler; the core action and the two calling modes come first. A few fragments ('Schemas: describe(kind='operations').') are terse to the point of being cryptic, and 'Marketplace writes for a proposed change' partially repeats the first sentence.

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

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

For a 16-parameter, nested, destructive mutation tool, the description does credibly cover the calling modes, the schema lookup path, and the return value. It omits idempotency semantics, batch failure behavior, and any authorization prerequisites, which matter given destructiveHint=true and no output schema.

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

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

Schema coverage is high at 88%, so the baseline is 3. The description goes beyond the schema by explaining the otherwise-unlabeled oneOf: 'Accepts operation/request or legacy actionType,' telling the agent there are two mutually exclusive call shapes and that one is legacy. It also points to describe(kind='operations') for operation-specific payloads rather than restating them.

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

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

The description opens with a concrete verb and resource set: 'Submit Ads, SP listing or eBay changes' and 'Marketplace writes for a proposed change.' That distinguishes it from read-side siblings like get_mutations and get_events. It stops short of explicitly naming the near-neighbor update_mutation, but the write-submission purpose is unambiguous.

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

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

'Marketplace writes for a proposed change' and 'Key grants choose review or direct execution' give real context on when this tool is the right entry point. The pointer to 'describe(kind='operations')' steers the agent for schema lookup. However, there is no explicit guidance on when to use update_mutation instead, nor any stated prerequisites (permissions, approvals) before calling.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds real value on top: ownership scoping ('this caller proposed') and terminal-state protection so the agent knows which rows will silently refuse. It omits whether a cancel is reversible, what happens on expectedVersion mismatch, and whether commenting requires a reviewer role.

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 sentence, front-loaded with the primary mutating operation, with the two action modes and their gates compressed into parentheticals. No filler and no repetition of annotation fields.

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 cancel path is fully specified for correct invocation, but the comment path has no state constraints, no role/permission requirement, and no indication of what a reviewer reply attaches to. For a destructive mutation tool with six parameters and no output schema, that asymmetry leaves a real invocation 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?

With schema coverage at 67%, the description carries the decisive semantics by binding each action value to its intent, which the schema's enum does not explain. It still leaves mutationId unexplained and doesn't tie reason/expectedVersion/body to their actions beyond what the schema descriptions already say.

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 both operations precisely (cancel a proposed change, post a reviewer comment) with the `action` enum values inline, so the agent knows exactly what the tool does. The phrase 'this caller proposed' and the mutation vocabulary separate it cleanly from submit_mutation and get_mutations.

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?

States explicit preconditions for cancel (pending or needs_revision only; approved, declined, executed stay closed), which is strong when-to/when-not guidance. It stops short of naming alternatives such as get_mutations for reading or submit_mutation for proposing, and gives no conditions for the comment path.

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