pricewatcha

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

Annotations already indicate it's a write operation (readOnlyHint=false, destructiveHint=false), so the safety profile is known. The description adds valuable context about required API key, failure error format, and threshold logic beyond annotations, though it doesn't cover idempotency or side effects.

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

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

Three sentences, front-loaded with purpose and usage, then API key requirement, then error handling. Every sentence earns its place with no fluff.

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

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

Given the complexity (9 parameters, write operation) and the presence of an output schema (which handles return values), the description covers purpose, usage, requirements, and error behavior adequately. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds semantic relationships: explains that notify_on_drop/rise work without thresholds and that min/max_threshold_price are for target prices, and mentions the requirement of at least one. This adds meaning beyond the schema descriptions.

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

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

States a specific verb and resource ('Create a price alert for a product') and explicitly distinguishes itself from update_price_alert and delete_price_alert by naming creation. An agent can identify the tool's purpose immediately.

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

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

Provides clear context on when to use specific parameters and the mandatory constraint ('At least one of those four settings is required'), but does not explicitly route to sibling tools like update_price_alert for modifications.

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 (destructive, idempotent, not read-only), it discloses the authentication requirement and where to obtain the key, plus the structured failure shape. It does not add much on blast radius, but the auth-sourcing detail is genuine value the annotations lack.

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 auth requirement, then failure behavior. No filler, though the error-field enumeration is somewhat verbose for a description.

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 the explicit enumeration of error fields is partly redundant, but the description still covers auth, destructive semantics, and failure handling adequately for a two-parameter 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 100%, so both api_key and alert_id are already documented in the schema; the baseline is 3. The description only adds the URL for obtaining the key, which is marginal but not meaningless.

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'), so the operation is unambiguous. It does not, however, distinguish itself from siblings like update_price_alert or get_price_alert beyond the obvious verb difference.

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 no when-to-use guidance, no prerequisites beyond the API key, and never mentions alternatives such as update_price_alert (to modify) or list_price_alerts (to find the ID). Usage is only implied by the name.

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, and non-destructive behavior. The description adds valuable context about failure responses, detailing the structured error object fields, which goes beyond the annotations. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, then covers both success and failure outcomes. No extraneous information, every sentence earns its place.

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

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

Given the tool is simple (zero parameters, read-only, idempotent) and an output schema exists (per context), the description covers the essential behavioral aspects including error handling. It is sufficiently complete for an agent to use effectively.

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 are no parameters, so the schema coverage is 100%. The description does not need to add parameter details, and the baseline for zero parameters is 4. The description is adequate.

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

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

The description clearly states the tool checks whether the Pricewatcha public API is available, with a specific verb and resource. It distinguishes from sibling tools like get_job_status or search_products by focusing on API health.

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

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

The description implies usage for checking API availability but does not explicitly specify when to use or avoid this tool compared to alternatives. There is no mention of prerequisites or exclusions, leaving the agent to infer based on tool name and purpose.

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 annotations (readOnly, idempotent), it clarifies that HTTP 200 indicates job lookup success, not a transport error, and details the error object structure on failure. No contradiction with annotations.

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

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

Three concise sentences with no filler. Front-loaded with core purpose, immediately actionable.

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

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

Given the output schema exists, the description covers all necessary states (statuses, populated fields on completion/failure) and error details, making it complete for a polling 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 already describes job_id with 100% coverage; description adds extra context that job_id comes from track_product, which aids understanding beyond the schema.

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

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

The description starts with a specific verb ('Poll') and resource ('async tracking job by job_id'). It lists exact statuses and outcomes, clearly distinguishing from siblings like get_product or get_api_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?

It implies usage after initiating a tracking job (job_id from track_product) and explains behavior for completion and failure, but does not explicitly exclude use cases or mention when not to use.

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 safety is covered. The description goes further by disclosing the auth prerequisite (API key with pwk_live_ prefix from a specific profile URL) and the failure contract (error.code, error.message, error.http_status, error.retry_recommended, error.retry_after_seconds), which is genuinely beyond the annotations.

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

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

Three sentences, front-loaded with the core action before the auth and error details. No filler, though the error-field enumeration is slightly list-heavy for a read tool whose output schema already 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?

For a two-parameter read tool with an output schema and full annotation coverage, this covers credentials, the identifier source, and failure behavior. Only the when-to-choose-this-over-siblings decision is left unstated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds value by restating the key format and linking the URL where the key is issued, plus the error fields that parameters feed into.

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 ('Get one price alert by alert_id'), which separates it from the list/get-history siblings by scope. It never names an alternative tool, so sibling differentiation is implied rather than explicit.

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

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

The description implies single-record lookup, but offers no when-to-use guidance or exclusions relative to list_price_alerts or get_price_history. The only routing aid is the alert_id provenance note that lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context about structured error objects on failure and mentions return components (aggregates, trend), going beyond annotations without contradiction.

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

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

Two sentences with no wasted words. First sentence covers purpose and return, second covers error handling. Very efficient.

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

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

Given low complexity, annotations, and output schema, the description adequately covers purpose and key behaviors. However, it omits potential constraints like date range limits or pagination, which could be relevant.

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 'Public product ID' for product_id. The description does not add any additional meaning to the parameter beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'historical prices' for a product, specifying return types (aggregates, trend, data points). It naturally distinguishes from siblings like get_product or search_products.

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

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

The description implies usage for retrieving price history but lacks explicit guidance on when to use this tool versus alternatives (e.g., get_product) or any exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds transparency by detailing the structured error object returned on failure, including fields like error.code and error.retry_after_seconds. No contradictions.

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

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

Two sentences, no redundant words. The main purpose is front-loaded, and the error information is efficiently appended. Every sentence contributes meaningfully.

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

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

For a simple retrieval tool with one parameter, rich annotations, and an output schema (mentioned but not shown), the description covers the essential: what it retrieves, how to specify the product, and error handling. No gaps.

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

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

Schema coverage is 100% with a description for product_id. The description adds value by giving example IDs and linking them to completed jobs, which provides context beyond the schema's minimal description.

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

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

The description clearly states the tool's purpose: to get structured product price intelligence by product_id. It provides specific examples of valid IDs (demo_iphone_15_pro, prod_xxx) and distinguishes itself from siblings that handle API status, job status, price history, search, or tracking.

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

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

The description implies usage context by specifying that product IDs come from completed jobs and providing example IDs. However, it does not explicitly state when to use this tool over siblings or when not to use it.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds valuable beyond-annotation context: the API key requirement, key format, where to obtain it, and the exact structure of the failure error object including retry fields. It doesn't contradict 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 sentences, front-loaded with purpose, then prerequisites, then failure behavior. Every sentence earns its place with no repetition or filler.

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

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

For a two-parameter read-only tool with annotations and an output schema, the description is complete: purpose, auth prerequisite with key format, and failure return shape are all covered. 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 description coverage is 100%, so the schema already documents api_key and product_id fully. The description adds the key format and source URL, which marginally enriches the api_key parameter, but does not add syntax or semantics beyond the schema.

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

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

States a specific verb and resource: 'Check whether your account watches a product for continuous updates.' Distinguishes clearly from siblings like watch_product and unwatch_product, which mutate state, and list_watchlist, which lists entries.

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

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

The description implies usage by stating the tool checks watch status for an account/product, but doesn't explicitly say when to use this vs. list_watchlist or get_product. No when-not or alternative routing is provided.

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), so the bar is lower. The description adds real value beyond that: the required pwk_live_ API key with its profile URL, and the structure of the failure response including retry_recommended and retry_after_seconds — operationally useful context 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 tight sentences with the purpose front-loaded, followed by the filter and then auth/error handling. The enumerated error fields are somewhat listy but each earns its place by telling the agent what to inspect on failure.

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

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

With an output schema present, the description needn't explain success returns, and it correctly spends its budget on the auth prerequisite and error contract. Nothing critical for invoking the tool correctly is missing, though it could note whether results are paginated or filtered server-side.

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 parameters (api_key, product_id) are already documented in the schema. The description restates the product_id filter without adding format, syntax, or behavioral detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('List your price alerts') and the optional filter, which clearly separates it from get_price_alert (single) and create/delete_price_alert. It does not explicitly name a sibling alternative, so it falls short of the top band.

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 notes the product_id filter is optional, implying the no-filter case lists everything, but it never says when to prefer this tool over get_price_alert or list_watchlist. 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 declare the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lowered, yet the description adds real behavioral detail: the auth requirement and its source, plus the exact error object shape (error.code, error.message, error.http_status, error.retry_recommended, error.retry_after_seconds). That error contract is genuinely valuable for retry logic and goes well beyond the annotations.

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

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

Three front-loaded sentences: purpose first, auth second, error behavior third, with no filler. The error-field enumeration is long but each field is load-bearing for an agent handling failures.

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 shape needn't be explained, and the description covers the auth prerequisite and failure contract. For a simple paginated read tool this is close to complete, with only the sibling-routing guidance missing.

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

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

Schema description coverage is 100%, so the schema already documents limit (default 50, max 200), offset, and the api_key format. The description only restates the api_key format hint (pwk_live_...) with no additional semantics, so the baseline 3 for a fully-covered schema 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 a scope qualifier ('for continuous price updates') that distinguishes it from a general product listing. It does not explicitly contrast with the nearby sibling list_price_alerts, so an agent must infer the product-vs-alert distinction, but the 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?

The description states a prerequisite (a Pricewatcha API key, with a URL for obtaining it) which is useful context, but it gives no guidance on when to choose this tool over siblings like list_price_alerts, get_watch_status, or get_product. Usage is only implied by the name.

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, and non-destructive hints, so the description adds value by explaining exact query behavior: token AND, irrelevant word order, and minus-prefixed exclusions. It also documents the exact failure response shape, which is useful operational behavior not captured by the annotations.

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

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

The description is three sentences, all of which are informative and non-redundant. The primary action is front-loaded, key query semantics are compactly explained, and the error object detail is concrete without 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?

With only one input parameter, full schema coverage, output schema presence, and safety/caching hints already provided by annotations, the description fills the remaining gaps: search semantics, scope of results, and structured failure mode. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

The schema already covers the query parameter 100%, so the description is not strictly required to add parameter info. It does add meaningful behavior beyond the schema by explaining word order, AND semantics, and exclude-term syntax, which helps the agent formulate a properly structured query.

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

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

The description opens with a specific verb and resource: 'Searches the Pricewatcha product catalog by keyword.' It also distinguishes this tool from siblings by clarifying that it returns product-level data only, not user accounts or alert settings, and explains the query semantics. This is a clear and non-tautological statement of what the tool does.

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

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

The description makes clear it is for keyword-based product catalog search and explicitly excludes user accounts and alert settings, giving a when-not-to-use signal. However, it does not explicitly name alternative sibling tools (e.g., use get_product for a direct product lookup), so the guidance is helpful but not fully exhaustive.

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

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

The description goes well beyond annotations by disclosing server-side wait time (~25s), two possible status paths, the job_id polling mechanism, and the full structured error object shape. Since annotations are all false and provide little safety information, this behavioral detail is especially valuable.

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 focused sentences: the first states the action, the second covers the normal and slow paths, and the third covers errors. There is no filler or repetition, and key behavioral details are front-loaded.

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

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

The description fully covers the main invocation flow, timeout behavior, polling fallback, and error handling. Since an output schema exists, return value details are not the description's burden, and the tool's complexity is well supported by the provided text.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level detail beyond the schema; it only mentions job_id, which is part of the response, not a parameter. The schema already documents url, watch, api_key, and refresh 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 states a specific verb and resource: submit a public product URL for price tracking. It clearly explains the action and result, but it does not explicitly contrast track_product with similar siblings like watch_product or get_product, so sibling differentiation is left implicit.

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

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

The description gives clear context for the async flow: fast shops return completed, slow jobs return running with a job_id and instruct the agent to poll get_job_status. It does not explicitly state when to choose this tool over watch_product or when not to use it, but the polling guidance is actionable.

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 description's added value is the auth requirement (pwk_live_ key with a URL for obtaining it) and the failure precondition. It doesn't describe reversibility or rate limits, but the destructive/idempotent profile is covered by annotations, so this is solid.

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 before the precondition and auth detail. The key-prefix format slightly duplicates the schema, but the URL for obtaining the key is genuinely additive and nothing is wasted.

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

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

Covers purpose, precondition, auth requirement, and error-object shape, while an output schema exists to carry return values and annotations carry the safety profile. An agent has everything needed to invoke this correctly and interpret failure.

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 product_id are already documented in the schema. The description only restates the api_key format, adding nothing beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove a product from your account watchlist') and is easily distinguished from siblings like watch_product, track_product, and delete_price_alert. It also flags a key scope condition (fails with an active price alert) that shapes selection.

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

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

Gives clear context for when the call succeeds and the precondition that blocks it ('Fails while an active price alert exists'), which implicitly routes the agent to delete the alert first. It never names the alternative tool explicitly, so the routing is inferred 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?

Goes well beyond annotations by disclosing auth requirements (API key from a specific profile URL) and the precise shape of the failure response (error.code, error.message, http_status, retry_recommended, retry_after_seconds), which is valuable for a mutation tool.

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

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

Front-loads the core action, then constraints, auth, and error shape in a compact multi-sentence block. Slightly dense but every sentence carries distinct information.

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

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

For a mutation with 10 params, the description covers behavior, constraints, auth, and error handling; an output schema exists so return-value detail is not needed. Missing only edge-case guidance on partial-update semantics.

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 60%; the description compensates by explaining the notify_on_drop/notify_on_rise threshold-free semantics and the 'at least one setting must remain' rule, adding meaning beyond the raw schema.

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

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

States a specific verb+resource ('Update a price alert') and enumerates the exact mutation modes (notify_on_drop/rise, thresholds, is_active), clearly distinguishing it from create/delete/get/list siblings.

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

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

Provides the operational constraint that at least one setting must remain, and names which settings are switchable, but does not explicitly state when to prefer this over create_price_alert or delete_price_alert.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, and the description adds valuable behavioral detail: authentication requirements, the specific key format, and the complete structure of failure responses including retry guidance. This exceeds what the 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?

Three sentences that are front-loaded with the primary action, then prerequisites, then error behavior. No filler; every sentence adds distinct value.

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

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

An output schema exists, so return values need not be explained. The description covers prerequisites and error shape. It could note the idempotent nature explicitly, but the annotations already cover safety.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description mentions the API key and its format, but adds no syntax or format details beyond what the schema provides for product_id or the key. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Add a catalog product to your account watchlist') and explains the consequence ('the price scheduler keeps updating it'). It distinguishes itself from siblings like track_product and unwatch_product by being the watchlist-add action.

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?

Explains the intended effect and prerequisite (API key) clearly, implying when to use it (to start watching a product). It does not explicitly contrast with sibling tools like track_product or unwatch_product, which would strengthen routing, but the context is clear.

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