pricewatcha

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

Adds materially beyond the annotations by disclosing the required Pricewatcha API key format and where to obtain it, and by describing the structured error object (error.code, error.message, error.http_status, error.retry_recommended, error.retry_after_seconds). The retry fields give an agent actionable recovery behavior that the openWorldHint/idempotentHint annotations alone would 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 purpose, then constraint, then auth, then error shape — every sentence carries operational information. The final error sentence is long but justified for a tool whose failure modes the agent must handle.

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?

An output schema exists so return values need no prose, and the description still covers the two things it must: credential prerequisites and the failure contract. With 9 parameters, 2 required, and full schema coverage, 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%, so the baseline is 3, but the description supplies a genuine cross-parameter rule the schema cannot express: at least one of notify_on_drop, notify_on_rise, min_threshold_price, or max_threshold_price must be provided. It also clarifies the intent split between boolean flags and numeric thresholds.

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 price alert for a product") that an agent can immediately distinguish from list/get/update/delete siblings. It does not explicitly name update_price_alert as the alternative for modifying an existing alert, so it falls just short of full sibling differentiation.

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

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

Gives clear in-tool guidance on how to configure the alert: threshold-free booleans versus numeric target prices, plus the hard constraint that at least one of the four must be set. It does not address when to prefer this over update_price_alert or track_product, so there is no explicit exclusion or alternative routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds value annotations cannot: it names the credential format and where to obtain it, and it enumerates the exact structured error fields including retry_recommended and retry_after_seconds. It does not state whether deletion is irreversible or what happens to existing alert history, which is a small remaining gap.

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 prerequisite, then failure behavior. No wasted words, though the full field-by-field error enumeration is a bit heavier than needed when an output schema exists.

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

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

Auth requirement and failure semantics are spelled out, and an output schema exists so return values need not be restated. What is missing is the post-condition of deletion — permanence and effect on related resources — which matters for a destructive, non-readOnly operation.

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

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

Schema description coverage is 100%, so both api_key and alert_id are already documented, and the description adds no syntax, format, or sourcing detail beyond what the schema states. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ("Delete a price alert") that unambiguously identifies this as the delete operation among CRUD siblings like create_price_alert and update_price_alert. An agent can select it 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?

No guidance on when to use this versus alternatives (e.g. update_price_alert to disable an alert, or unwatch_product) and no preconditions such as needing the alert to exist or belong to the caller. The description simply assumes the reader already knows they want to delete.

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 this is a safe, idempotent read. The description adds genuinely new context: on failure the tool still returns a structured error object containing error.code, error.http_status, error.retry_recommended, and error.retry_after_seconds, which tells the agent how failures are surfaced and how to back off. Not a full 5 since rate limits and caching TTL of the status result are unstated.

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

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

Three short sentences with the core purpose front-loaded and the error shape second. The enumerated error fields are slightly list-heavy but each maps to a behavior an agent needs to react correctly.

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

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

For a zero-param, read-only status endpoint this covers purpose, success payload nature ('health and discovery metadata'), and failure shape. Since an output schema exists the return values needn't be spelled out, so remaining gaps (e.g. payload structure details) are acceptable.

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

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

The tool takes zero parameters, so there is nothing to document; a baseline 4 applies. The description correctly avoids redundant parameter chatter.

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 ('Check whether the Pricewatcha public API is available') and scopes it to the public API rather than job/watch status. Distinguishes it from siblings like get_job_status and get_watch_status by naming the target of the check.

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 health-check framing implies when to use it (availability probing), and the retry fields hint at a pre-retry check pattern, but the description never states when to call it versus alternatives or any prerequisites. Usage is inferred rather than explicit.

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

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

Goes well beyond the annotations: names the four possible statuses, explains that product is populated on completion and error on scrape failure, and clarifies that a failure still returns HTTP 200 (not a transport error) with a structured error payload including retry_recommended and retry_after_seconds. This is exactly the behavioral context annotations 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?

Front-loaded with the core action, then lifecycle and error details in compact sentences. The final sentence partially restates the earlier 'error is populated' clause, a small redundancy.

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

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

An output schema exists so return structure is already documented, and the description nonetheless covers the polling lifecycle and error semantics thoroughly. The remaining gap is polling cadence/backoff guidance, only indirectly signalled by retry_after_seconds.

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?

A single parameter with 100% schema description coverage, so the schema already carries the semantics. The description restates 'by job_id' and adds no format or sourcing detail beyond what the schema note provides.

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

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

States a specific verb and resource: 'Poll an async tracking job by job_id', and enumerates the statuses it returns. An agent can tell it is a job-status lookup, though it doesn't explicitly contrast with the similarly named sibling get_watch_status.

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

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

'Poll' implies repeated calls and the schema note 'Job ID from track_product' hints at the calling sequence, but the description never says when to call this versus get_watch_status or how often to poll. Usage is implied rather than 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?

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the description's added value is the auth requirement (pwk_live_ key with a URL to obtain it) and a precise failure contract including retry_recommended and retry_after_seconds, which tells the agent how to recover from errors. It stops short of describing the success payload, but that is covered by the 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?

Three short sentences, front-loaded with the core action, then auth, then error behavior. Every sentence carries actionable information; nothing is padding.

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-required-parameter read tool with full schema coverage, annotations, and an output schema, the description covers the remaining burdens: authentication setup and the error/retry contract. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and alert_id's schema description already points to create_price_alert/list_price_alerts, so baseline is 3. The description adds one genuine thing the schema does not: where to acquire the api_key (the profile#api-keys URL), which directly helps the agent satisfy a required 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?

States a specific verb and resource with explicit cardinality: 'Get one price alert by alert_id'. The singular-scope phrasing separates it from list_price_alerts and search-style siblings without requiring the agent to open 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?

The 'by alert_id' phrasing implies when this tool is appropriate versus the listing sibling, and the API key provenance gives practical setup context. However, it never states prerequisites, exclusions, or names an alternative explicitly ('use list_price_alerts to enumerate'), leaving selection to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is carried structurally. The description adds one genuinely useful behavioral fact — the structured error contract with retry_recommended and retry_after_seconds — which informs retry logic. However it says nothing about history depth, granularity, or result caps, and the error shape is likely already reflected in the output schema.

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

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

Two sentences, purpose front-loaded, no filler. The second sentence is a dense field enumeration, but each listed field carries retry-relevant information, so it 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?

With a full output schema, complete input schema coverage, and annotations covering safety, the description supplies what structured fields do not: the returned content categories and the failure/retry contract. Nothing required to invoke it correctly is missing.

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

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

There is a single required parameter with 100% schema description coverage ('Public product ID'), so the schema already does the work. The description does not mention product_id or clarify that it is a public (not internal) identifier, adding no meaning beyond the schema — baseline 3.

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

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

Specific verb+resource with the returned content enumerated (historical prices, aggregates, trend, data points) for a product. It does not explicitly contrast with siblings like get_product or search_products, which also surface product data, but the 'history/aggregates/trend' framing is distinctive enough to select on.

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

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

The use case (fetching price history for a known product) is implied by the description but never stated as when-to-use, and no alternative or prerequisite (e.g. resolve product_id via search_products first) is mentioned. Adequate minimum-viable guidance only.

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). The description adds genuine behavioral context by disclosing the structured failure object and its retry-related fields (error.code, error.retry_recommended, error.retry_after_seconds), which is useful for an agent deciding whether to retry.

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 primary operation and scope, followed by failure behavior. No filler or repetition of schema/annotation content.

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

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

For a single-parameter read-only tool with an output schema and full annotation coverage, the description provides what is needed: the purpose, ID examples, and structured error behavior. Return-value details are appropriately left to the 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 100%, so the single product_id parameter is already documented. The description adds value by giving concrete examples of the ID format ('demo_iphone_15_pro or prod_xxx from a completed job'), which clarifies meaning beyond the schema's generic 'Public product ID'.

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

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

The description states a specific verb and resource: 'Get structured product price intelligence by product_id'. It is clearly distinct in kind from sibling tools like search_products or get_price_history, though it does not explicitly name those alternatives to route the agent.

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 agent should use it when it already has a product_id from a completed job or a known demo ID. The description does not say when to prefer search_products or get_price_history instead, nor does it state 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 declare read-only, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the API-key prerequisite with a URL to obtain it, and a precise failure contract (error.code, retry_recommended, retry_after_seconds) which effectively signals rate limiting.

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, purpose front-loaded, then credential requirement, then error shape. No filler, though the error-field enumeration is slightly dense for a description that already has an output schema.

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

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

With a rich annotation set and an output schema, the description need only cover prerequisites and failure semantics, which it does. Nothing essential is missing, though it stops short of saying what a positive result contains or whether unwatched products are reported as false vs. an error.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description adds little for product_id. It does add the origin of the api_key credential (profile#api-keys), which is modest value beyond the schema's 'pwk_live_...' hint, matching the baseline 3.

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

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

Specific verb + resource: 'Check whether your account watches a product' states exactly what is returned for a single product. It is distinguishable from list_watchlist (enumerate all) and watch_product/unwatch_product (mutate), though it never names those siblings explicitly.

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

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

Usage is only implied: an agent can infer this is the single-product status lookup rather than a listing or a mutation. No explicit when-to-use, when-not, or routing to list_watchlist for a full enumeration is given.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the API key format and where to obtain it, plus the exact shape of the failure object (error.code, retry_recommended, retry_after_seconds). That retry guidance is behavior an agent cannot get from annotations.

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

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

Three short sentences, front-loaded with purpose then filter then prerequisites. The error-field enumeration is dense but each item earns its place for error handling; nothing is redundant.

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

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

An output schema exists, so return values need not be explained; the description correctly limits itself to the error object and auth prerequisite. For a two-parameter read tool with full annotation coverage, this is nearly complete, only lacking explicit sibling routing.

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

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

Schema coverage is 100%, so both parameters are already documented in-schema, making 3 the baseline. The description restates the api_key format and the optional product_id filter but adds no semantics beyond what the schema provides.

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

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

States a specific verb and resource ('List your price alerts') plus its optional filter, which distinguishes it from the singular get_price_alert sibling. It doesn't explicitly name a sibling to contrast against, so it falls short of full 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?

Usage is only implied by the name and the 'optionally filter' clause; there is no explicit statement of when to use this versus get_price_alert, get_price_history, or list_watchlist. The agent must infer the boundary from sibling names.

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, and non-destructive behavior, so safety is covered. The description adds value with the auth requirement and the structured failure contract (error.code, retry_recommended, retry_after_seconds), which annotations cannot express. It says nothing about pagination behavior or what an empty watchlist looks like, so beyond the error contract the added disclosure is modest.

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 core action before the prerequisite and the error contract. The enumerated error field list is slightly listy in prose but each item carries meaning for retry handling, so it earns its space.

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

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

For a read-only paginated list tool with a full output schema and safety annotations, the description covers purpose, auth, and failure semantics adequately. It skips pagination guidance and return-shape hints, but those are carried by the schema and output schema respectively.

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 parameters carry descriptions including defaults (limit 50, offset 0), so the schema does the heavy lifting. The description restates only the api_key requirement with the same pwk_live prefix already in the schema, adding no semantics beyond structured fields — 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 ('List products your account watches') with the added scope of continuous price updates, so an agent knows exactly what comes back. It does not, however, distinguish itself from close siblings such as list_price_alerts or get_watch_status, which an agent must infer.

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 prerequisite (a pwk_live API key and where to obtain it) is spelled out clearly, which is genuine usage guidance. But there is no statement of when to prefer this over list_price_alerts, get_watch_status, or search_products, and no exclusion conditions — usage 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 establish readOnly, idempotent, non-destructive and closed-world behavior, so the description only needs to add context. It does add valuable behavioral detail: the search grammar and the structured failure shape with error.code, error.retry_recommended and error.retry_after_seconds, which tells the agent how to react to failures. It omits pagination/result-count limits and empty-result 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?

Three dense sentences that front-load the core purpose and grammar before the return-scope and error details; nothing is filler. The error-field enumeration is slightly verbose for a description when an output schema exists, which keeps it below 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 one-parameter, read-only search tool with an output schema and full annotation coverage, the description covers purpose, query grammar and failure behavior. The main remaining gaps are result volume/pagination and empty-result handling, which are minor given the rich structured metadata.

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 required parameter with 100% schema description coverage, so the schema already documents the query, the token-AND rule and the minus-prefix syntax with the same example. The description largely restates this rather than adding syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Searches the Pricewatcha product catalog by keyword') and explicitly scopes the return to product-level data, ruling out user accounts and alert settings. That scope statement separates it from siblings like list_price_alerts and get_product without requiring the agent to inspect their schemas.

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

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

The description gives clear usage semantics for the query, including token-AND matching and minus-prefixed exclusion with a worked example, and the scope sentence implies it is the discovery tool rather than the single-item lookup. It stops short of explicitly naming alternatives such as get_product for direct ID lookups or stating when-not to use it, so it does not reach 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?

Adds substantial context beyond annotations: the ~25s server-side blocking wait, the two possible terminal statuses and what each means, the polling follow-up, and the exact error object shape including retry_recommended and retry_after_seconds. Annotations cover only safety flags, so this description carries behavior disclosure well.

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 action, then the outcome branches, then failure shape. No filler and every clause conveys actionable 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?

An output schema exists, so return-shape explanation is technically redundant, though describing status values is still helpful. The only real gap is that the description never touches the watch/refresh enrollment behavior, leaving that 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 100%, so url, watch, api_key, and refresh are all documented in the schema. The description adds no additional meaning about their semantics — notably it never mentions watch/refresh or the API key requirement they imply. 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?

Specific verb and resource: "Submit a public product URL for price tracking." It also distinguishes its async flow by naming get_job_status. However, it does not differentiate itself from the closely related sibling watch_product, which an agent could reasonably confuse for tracking enrollment.

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

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

The description clearly routes the agent forward in the workflow (fast shops → completed, slow jobs → poll get_job_status), which is genuinely useful usage guidance. But it gives no guidance on when to choose this tool over siblings like watch_product, get_product, or search_products.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real context beyond that: the failure precondition, the API key requirement with a location to obtain one, and the exact error object shape returned on failure. It doesn't say whether associated watch history is preserved, which would round out the destructive-behavior picture.

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

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

Four short sentences, front-loaded with the action, then the failure condition, then the auth requirement, then the error contract. No filler or repetition.

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

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

An output schema exists, so return-value detail isn't required, yet the description still summarizes the error object fields. Combined with annotations covering the safety profile, an agent has enough to call it and handle failure 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% with only two params, both already documented in the schema. The description adds the source URL for the api_key, which is the only semantic value beyond the schema. Baseline 3 applies when the schema carries parameter meaning.

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

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

States a specific verb and resource: 'Remove a product from your account watchlist.' Clear and unambiguous on what is happening. It does not explicitly distinguish itself from sibling watch/alert tools such as watch_product, track_product, or delete_price_alert, leaving the agent to infer the pairing.

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 concrete precondition — 'Fails while an active price alert exists for the product' — which implicitly tells the agent to clear alerts before unwatching. It stops short of naming delete_price_alert as the prerequisite step or comparing this to track_product, so the alternative isn't 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 idempotentHint=true; the description adds real context beyond that: the requirement to leave at least one setting, the pwk_live_ key source, and a full structured error contract (error.code, http_status, retry_recommended, retry_after_seconds). It stops short of stating that omitted fields are left unchanged or what clearing a threshold does.

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 sentences, front-loaded with purpose and the mutable-field list, followed by the constraint, auth, and error contract. It is tight overall, though enumerating every error field name is slightly verbose compared to what the output schema already provides.

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 mutation tool with destructive annotations and an output schema, the description covers auth, key constraints, and error behavior well. The main remaining gap is partial-update semantics (whether unspecified fields are preserved), which an agent would still need to infer.

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 60% schema coverage across 10 parameters, the schema already documents api_key, alert_id, and the null-to-clear threshold behavior. The description reinforces only the threshold-free notify_on_drop/notify_on_rise semantics and is_active; it says nothing about name, webhook_url, or notify_email, so it adds partial value but does not fully compensate for the coverage gap.

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

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

The description states a specific verb and resource ("Update a price alert") and enumerates the mutable fields: threshold-free notify_on_drop/notify_on_rise, thresholds, and is_active. This clearly separates it from create_price_alert, delete_price_alert, and get_price_alert even without naming them, though no sibling is referenced explicitly.

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

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

Usage is only implied: the agent can infer this is the tool for modifying an existing alert, and the constraint "At least one setting must remain" plus the API-key prerequisite are useful guardrails. However, there is no explicit when-to-use versus get_price_alert or delete_price_alert, and no guidance on partial-update expectations.

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 (idempotent, non-destructive, open-world), the description discloses the auth requirement and the exact failure shape including `retry_recommended` and `retry_after_seconds`, which is materially useful for error handling. It does not say what happens when a product is already watched, despite the idempotent hint.

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

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

Front-loaded with the action, then prerequisite, then failure behavior — a logical order with no filler. The error-field enumeration is slightly listy but earns its place for recovery guidance.

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

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

An output schema exists, so return values need no explanation, and the description covers auth and error recovery well. The only material gap is the missing clarification of the relationship to the near-identical `track_product` sibling.

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 parameters are self-documented, so the description's repetition of the `pwk_live_...` key format adds no new meaning. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Add a catalog product to your account watchlist') and adds the consequence ('the price scheduler keeps updating it'). It does not differentiate itself from the very similar sibling `track_product`, leaving an agent unsure which of the two is the right entry point.

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 scheduler consequence implies the use case, and the API-key prerequisite is stated, but there is no explicit guidance on when to choose this over `track_product` or how it relates to `unwatch_product`/`get_watch_status`. The agent must infer routing from names alone.

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