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

With no annotations, the description carries the full load and does well: it discloses the mutation path (real wp-admin category edit UI, not direct DB) and a side effect (site cache invalidation). It does not state overwrite semantics for existing SEO fields, required permissions, or what happens on an invalid term_id, which keeps it below 5.

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

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

The core action is front-loaded in the first sentence, followed by the rationale and the cache side effect. Three sentences with little waste, though the mechanism explanation is slightly repetitive.

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 3-parameter mutation tool with no annotations and no output schema, the description covers purpose, mechanism, rationale and one side effect. Missing pieces are the term_id sourcing and confirmation/return behavior after the write, so it is near-complete but not airtight.

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 0%, so the description must compensate. It explains what titolo_seo and meta_description hold (SEO title and meta description), but term_id — the most error-prone parameter — is never explained (which category identifier, how to obtain it, WordPress term semantics). Partial compensation only.

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: writes the SEO title and meta description of a product category. It also contrasts itself with the product counterpart ("a differenza dei prodotti"), which lets an agent separate it from aggiorna_seo_prodotto 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?

It gives a clear usage rationale: for categories, direct DB writes are not re-read by Yoast, so this UI-based path is "l'unico modo affidabile". The implicit exclusion (do not use this for products, use the product tool) is present but the sibling is never named, so no explicit 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?

No annotations are provided, so the description carries the full load and does so: it discloses that existing values are overwritten, that the effect is public (SERP), that site cache is invalidated, and that the plugin keeps baseline and previous versions restorable in the SEO tab. It also returns before/after values and shifts responsibility for similarity scores to the user.

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

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

Front-loaded with the core action and the overwrite warning, then the pre-call workflow. It is dense and the parenthetical asides make it slightly long, but nearly every sentence carries operational 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?

For a mutation tool with no annotations and no output schema, the description covers safety, reversibility, cache side effects, return values (before/after) and the compliance workflow. Only the identification/validation semantics of the parameters, notably prodotto_id, are 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 0% across 5 parameters, so the description must compensate. It explains `origine` well (competitor site, with an example) and indirectly identifies the three text fields, but says nothing about `prodotto_id` or any format constraints on the text fields, leaving meaningful gaps.

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

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

Opens with a specific verb and resource set (writes/overwrites SEO title, meta description, focus keyword of a product) and differentiates from siblings by naming ripristina_seo_prodotti for restoring and controlla_somiglianza for pre-checks. An agent can distinguish it from leggi_seo_prodotto or aggiorna_seo_categoria 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?

Gives an explicit conditional workflow: if the texts derive from a competitor analysis, first run controlla_somiglianza, show score and passages, explain the 0-9 scale, let the user choose, apply only after their choice. Also says when to fill `origine` and how to undo via ripristina_seo_prodotti.

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?

No annotations, so the description carries the burden and does well: it discloses the no-network guarantee, that input is single files or folders, and the non-obvious page-type inference behavior with `sito` as a fallback label. It stops short of describing the response shape, but the output is partially implied ('campi SEO, vocabolario, stile e intenzione, estratti').

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 sibling comparison and the offline rationale, so the agent gets the key differentiator immediately. Somewhat dense with parentheticals and the closing rules sentence, but 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?

Given no output schema and 3 undocumented params, the description covers purpose, when-to-use, offline behavior, page-type resolution, and roughly what the analysis returns. The only material omission is the meaning of `caratteri_per_pagina`.

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 0%, so the description must compensate. It clarifies `percorsi` (single files or folders) and explains `sito` as merely a label for pages that don't declare their address — genuinely non-obvious semantics. However `caratteri_per_pagina` (default 600) is left completely unexplained, leaving a real 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?

States a specific verb ('analizza') and resource ('pagine .html salvate dall'utente'), and anchors it against the sibling analizza_seo_site ('Stessa analisi di...'). The offline/no-network scope makes it trivially distinguishable from the live-site sibling.

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

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

Explicitly states when to use it — 'per i siti che bloccano gli strumenti automatici o costruiscono le pagine con JavaScript' — which implicitly routes live, accessible sites to analizza_seo_site. It also names a downstream obligation (controlla_somiglianza before applying) and inherits analizza_seo_site's usage rules.

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

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

With no annotations, the description carries the full burden, and it does disclose a lot: robots.txt compliance, pauses, Retry-After, duration (tens of seconds), no JavaScript unless browser mode, private-network rejection, local storage of analyzed texts, and that a summary is sent to the plugin. However, the numerous behavior and performance details are buried across a very long paragraph rather than front-loaded, and the report's exact shape is only partially conveyed, so the signal is strong but dense.

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?

Content is front-loaded (purpose, then report contents, then COME USARLO, then per-parameter notes) which suits a 7-parameter tool with complex behavior. Still, it is very long and some sentences overlap (usa_browser and browser_visibile repeat environment-variable and 403/429 logic), costing a little efficiency.

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 no output schema and no annotations, the description supplies what an agent needs: report contents (SEO fields, vocabulary, style/intent signals per 1000 words, structure, repeated messages, estratto), the valutazione 0-9 scale, the 'Il tuo sito' marker, plugin persistence, and all fallback paths. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: url can be a site, a section (perimetro), or a category page with different sampling behavior; caratteri_per_pagina (0 = none, max 2000, affects token cost); max_categorie/max_prodotti raise the sample to a cap (10 and 30); usa_curl, usa_browser, browser_visibile each have explicit conditions. The cap phrasing '(10 e 30)' is slightly ambiguous about which limit maps to which parameter, and defaults are not stated, keeping it below 5.

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 (analizza a campione) and a specific resource (il sito di un altro negozio, di norma un concorrente), with the exact scope of what gets fetched: home, sitemap, categories, ~10 products. It is clearly distinguishable from siblings like analizza_pagine_salvate (named as a fallback) and controlla_somiglianza (named as the downstream step).

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 routing: when to use curl (only if the user asks, 429 fallback), when to use browser/visible browser (only on request or after a 403/429 refusal), and the fallback to analizza_pagine_salvate if the browser still fails. It also dictates the downstream workflow (pass texts to controlla_somiglianza, ask the user for the acceptable similarity level, show a preview) and warns against copying competitor text.

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?

No annotations, so the description carries the full burden. It does disclose the key behavioral fact — the pending change is discarded and not saved — but says nothing about what happens if no modification is pending, whether a confirmation is required, or whether any state is returned.

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

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

A single short sentence with the effect front-loaded and zero filler. Nothing could be removed without losing meaning.

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

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

For a zero-parameter, no-output-schema cancellation tool with no annotations, the description covers the essential action and non-persistence. It falls short only on edge-case behavior (no pending change) and any confirmation 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies no input is needed.

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

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

States a specific verb (scarta) and resource (la modifica in sospeso) and ties it to the originating family of tools (prepara_*), which cleanly separates it from conferma_modifica_in_corso. An agent can identify the operation without opening any schema.

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

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

The phrase 'da un tool prepara_*' implies the sequence (call after a prepara_* tool, instead of confirming), but no explicit when-to-use/when-not-to-use guidance or named alternative is given. Usage is inferable but not 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?

With no annotations, the description carries the full burden and does substantial work: it discloses that this writes directly to the DB, also touches the WooCommerce lookup table, and invalidates the site cache, including the reason ('altrimenti il prezzo nuovo non si vedrebbe online'). It omits permissions, atomicity/partial-failure behavior, and reversibility, which keeps it below a 5 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?

The write action and the input requirement are front-loaded, and the parenthetical on cache invalidation earns its place by explaining non-obvious side-effect behavior. The nested parentheses in the first clause make the opening slightly harder to parse than ideal.

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 tool with no annotations and no output schema, this covers the critical operational facts an agent needs: input shape, downstream WooCommerce propagation, and cache consequences. Missing only failure/rollback semantics and what the call returns on success or partial 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 coverage is 0% and the single parameter is an untyped array with additionalProperties, so the description must compensate — and it does by naming the required per-element keys `id` and `prezzo_regolare_nuovo` and by pointing to calcola_aggiornamento_prezzi as the canonical shape. It still leaves element types and number formatting unspecified.

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 ('scrive i nuovi prezzi') and ties the input to the output of the sibling calcola_aggiornamento_prezzi, so the agent can tell it apart from that calculator and from the cache-purge tool without opening any schema. The scope (direct DB write plus WooCommerce lookup and cache invalidation) is concrete and 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 establishes the pipeline: the argument must be the approved list produced by calcola_aggiornamento_prezzi, which implies calculate-then-approve-then-apply. It does not state explicit exclusions (e.g. when to prefer prepara_modifica_prezzo_prodotto instead), so it falls short of a full when/when-not statement.

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

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

With no annotations present, the description carries the full burden and does well: it declares read-only behavior, states that variable products are excluded from the calculation, and describes the returned fields. It does not say what happens if both percentuale and delta are supplied, how currency/rounding is handled, or what errors may occur when the category has no simple products.

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?

Compact and front-loaded with the purpose before the workflow note and the parameter constraint; every sentence adds information. The awkward line wrapping and parenthetical nesting slightly reduce readability but do not inflate length.

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

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

No output schema exists, and the description does supply the return semantics (current vs. calculated price). Combined with the read-only guarantee and the review-before-apply workflow, an agent has enough to call it correctly, though edge-case behavior (both or neither parameter, empty categories) remains unstated.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the two optional parameters: it explains percentuale as a percentage (examples 10/-15) and delta as a fixed currency amount (example -5), plus the mutual-exclusivity rule. Only categoria is left implicit, which is tolerable but not documented.

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 (calcola_aggiornamento_prezzi) and scopes it precisely to simple products of one category, explicitly excluding variable products. It also describes the output shape (current price + calculated price), which distinguishes it cleanly from the sibling applica_aggiornamento_prezzi.

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

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

Explicitly frames the tool as read-only and part of a two-step workflow: show results to the user, then call applica_aggiornamento_prezzi. It also states the constraint to specify only one of percentuale or delta. Missing only an explicit statement of when not to use it (e.g. for variable products, beyond the parenthetical note).

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

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

With no annotations at all, the description carries the full burden and does add real behavioral value: it discloses a non-obvious side effect (site cache invalidation) and explains why it is required ('altrimenti la modifica non si vedrebbe online'), which matters because purga_cache_sito exists as a separate sibling. Gaps remain around error behavior with no pending draft and whether the pending state is cleared afterwards.

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

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

Two short clauses, front-loaded with the action, and the parenthetical rationale for cache invalidation earns its place. The '(click su "Aggiorna")' UI hint is mildly extraneous but small.

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, no-annotation, no-output-schema tool, the description covers the action and the cache side effect but omits the post-state (is the pending modification consumed?) and failure modes, which an agent needs to decide whether a retry or an annulla_* call is appropriate.

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 per the baseline there is nothing for the description to disambiguate. It correctly avoids inventing parameter detail.

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

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

Uses a specific verb ('Salva'/'conferma') and resource ('la modifica lasciata in sospeso') and explicitly ties itself to the prepara_* staging tools, so an agent can place it in the two-phase write flow. It does not explicitly differentiate itself from the sibling annulla_modifica_in_corso, which is the one nearby alternative an agent could confuse it with.

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

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

Usage is implied rather than stated: the phrase 'la modifica lasciata in sospeso da un tool prepara_*' tells the agent this is the commit step after a staging call, but it never says what happens if no modification is pending, nor does it name annulla_modifica_in_corso as the branch for discarding instead.

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?

No annotations are provided, so the description carries the full burden and does so well: it explains the underlying algorithm (shared runs of at least 5 words), the calibration of scores 0-9, the non-binding nature of the verdict and the user's final say, and it names an output field (passaggi_simili) plus the caveat that product names inflate the score. What it leaves implicit is prerequisites (what happens if no site has been analyzed yet) and error behavior, which keeps it off a 5.

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

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

Front-loaded with the purpose and scale, then a computation block, then the usage protocol — a sensible ordering. It runs long and repeats the user-retains-control point ('non e' vincolante', 'l'ultima parola e' dell'utente'), which could be tightened without losing meaning.

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

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

With no output schema and no annotations, the description supplies the interpretation guide for the score and names the fields returned (`accettabile`, `passaggi_simili`), which is what an agent needs to report results correctly. Missing only edge-case handling, e.g. what occurs when no site has been analyzed or when testo is empty.

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 0%, so the description must compensate for all four parameters and it largely does: testo implied as the text under review, sito ('vuoto = tutti quelli analizzati', with the casualbay.it example), soglia (0-9, activates the `accettabile` field), and riferimenti (extra manual comparison texts). The only gap is that the null/default semantics of soglia (no verdict emitted) are inferred rather than stated.

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

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

States a specific action (measuring textual similarity) against a named source (texts from a site analyzed with analizza_seo_sito, or manually supplied texts) with the output scale spelled out. Sibling tools are clearly differentiated: analizza_seo_sito analyzes a site, this one judges whether OUR text borrows from it.

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 trigger ('Usalo su ogni testo scritto prendendo spunto da un concorrente ... PRIMA di applicarlo') plus a prescribed workflow: show score, explain the scale, ask the user for the soglia, never choose it autonomously, do not apply anything until decided, and offer a rewrite and re-check if exceeded. No alternatives need to be considered because the conditions are stated outright.

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

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

With no annotations, the description carries the full burden and it partially does so: it discloses the scope limit (only published products), the notable business rule that variable products are excluded because they have no own price, and the filtering behavior that clean products are omitted from results. It does not state that the operation is read-only, nor whether there are result-size limits or pagination — meaningful gaps for an unannotated 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?

The core scope ('Prodotti pubblicati ma incompleti') is front-loaded and every clause adds a real criterion rather than filler. It is one dense run-on sentence with parenthetical asides, which is slightly harder to scan than a bulleted criteria list would 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?

An output schema exists, so return-shape explanation is unnecessary, and the description gives the agent everything needed to interpret the result set, including the important caveat that non-problematic products are absent. The only shortfall is the absence of any routing guidance relative to the many sibling product-listing tools.

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 0% and the single parameter's title ('Soglia Descrizione') is opaque on its own; the description compensates by explaining that it is a character-count threshold below which a description is considered too short. The default value of 50 is in the schema but the description never mentions units or reasonable ranges beyond 'caratteri'.

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 analytical task: identifying published products that are incomplete, and enumerates the exact defect criteria (missing featured image, missing category, missing/zero/invalid price, short description). It is clearly distinct from siblings such as lista_prodotti or prodotti_in_bozza, though it never explicitly contrasts itself with them.

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 defect list — an agent can infer this is a pre-publish audit tool, but there is no explicit 'use this when...' statement and no mention of how it relates to lista_prodotti or prodotti_in_bozza, which could plausibly overlap.

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

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

With zero annotations the description carries the full burden and does so: the product is created as a draft and never published, the first image becomes the featured image while the rest go to the gallery, and the response contains an `avvisi_seo` field that signals SEO problems. It also discloses the human-in-the-loop approval requirement for competitor-derived copy, which is real operational 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 core action and its key constraints are front-loaded in the first sentences, with the approval workflow placed afterwards as a conditional block. It is somewhat long and the parenthetical about the plugin tab is incidental, but nearly every sentence carries 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?

For a 9-parameter creation tool with no annotations and no output schema, the description covers state (draft), media handling, price format, array alignment, response field `avvisi_seo`, and the surrounding workflow. It does not address whether `categoria` must already exist, which is the main open question an agent would have before calling.

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 0% across 9 required parameters, so the description has to compensate, and it does for the error-prone ones: prezzo_regolare must use a period as decimal separator, and alt_immagini must contain one element per entry in percorsi_immagini in the same order. The SEO trio (frase_chiave_focus, titolo_seo, meta_description) and titolo/categoria are only named or implied rather than explained, leaving a small 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?

States a specific verb and resource plus the resulting state: 'Crea un nuovo prodotto WooCommerce IN BOZZA', and enumerates the fields it populates. It also explicitly distinguishes itself from the sibling aggiorna_seo_prodotto ('non serve piu' chiamare aggiorna_seo_prodotto dopo'), so an agent can route between them without reading 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?

Gives explicit preconditions (if the texts derive from analizza_seo_sito or analizza_pagine_salvate, first run controlla_somiglianza and let the user pick a level) and explicit post-conditions (it is not published; review and publish from wp-admin, see prodotti_in_bozza). It also states a negative case: no need to invalidate the site cache.

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

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

With no annotations, the description carries the full burden. It does disclose the key behavioral trait — that the response contains personal data (name, email, phone, addresses) and should be used restrictively — but it never states that this is a read-only operation, what happens for a nonexistent order id, or any permission requirement.

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

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

One dense sentence with the payload contents front-loaded, followed by a short usage caution — no filler. The enumerated field list is long but each item tells the agent something it would otherwise have to discover by calling the tool.

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

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

There is no output schema and no annotations, so the description must describe the return payload — and it does so thoroughly, including the PII disclosure that governs how results should be handled. The remaining gap is routing guidance versus lista_ordini and error behavior for a bad id.

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 0% and the single parameter ordine_id has no title-level documentation either. The description only implies that an order must be identified ('di un ordine'); it adds no meaning about the id's origin, type, or format, so it fails to 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 names the resource (a single order's full detail) and enumerates exactly what it returns: line items with product ids, amounts (subtotal, discount, shipping, tax), payment/completion dates, shipping method, customer note and PII. This clearly separates it from the sibling lista_ordini, though it never names that sibling 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?

'Usalo solo quando serve davvero' signals that this is a heavy, privacy-sensitive call to be used sparingly, which is useful context. However, it gives no concrete condition, no exclusion rule, and never points to lista_ordini as the lighter alternative for browsing orders — the agent must infer the boundary.

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?

No annotations are provided, so the description carries the full burden; it discloses that this is a read of Yoast's own computed analysis and enumerates the content categories returned (problemi, miglioramenti, risultati buoni), which is valuable since there is no output schema. It omits any mention of permissions, caching/staleness, or behavior when analysis hasn't been run.

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 claim (real Yoast verdict) and then the workflow guidance; two sentences, both earning their place. The 'non un'approssimazione: e' l'analisi calcolata da Yoast stesso' clause is slightly redundant with 'verdetto REALE' but serves differentiation.

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

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

With no annotations and no output schema, the description compensates by explaining what the result contains and how it fits into the SEO update workflow. A reader knows enough to call it correctly; only edge-case behavior (missing/invalid prodotto_id, unanalyzed product) is unaddressed.

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

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

Only one parameter with 0% schema description coverage, but its name prodotto_id is self-explanatory, so the description loses little by not elaborating. No added meaning about the identifier's format or source is given, keeping this at an adequate baseline.

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

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

States a specific verb (legge) and resource (analisi SEO Yoast di un prodotto), and explicitly frames itself as the authoritative verdict rather than an approximation, which implicitly separates it from approximation-style siblings. It does not explicitly name leggi_seo_prodotto, so an agent must still infer which sibling is the approximation.

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

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

Gives an explicit usage sequence: 'Usalo dopo aggiorna_seo_prodotto' and the goal of checking whether anything is still missing (e.g., an outbound link, minimum text length). That is clear when-to-use guidance tied to a named sibling, though it never states when not to use it or what to use instead.

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?

No annotations are provided, so the description carries the full burden. It discloses that it is a read (same content as leggi_seo_prodotto) and that it works on legacy products, but not how it behaves with invalid or missing ids, partial failures, or empty input. Adding the legacy-product nuance is real value, but key mutation/error semantics remain undisclosed.

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 core behavior, followed by useful context. The parenthetical is efficient; the 'ottimizza SEO' button reference is slightly implementation-flavored but earns its place as usage 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?

With an output schema present, the description need not explain return values, and for a single-parameter batch reader it covers purpose, batch semantics and usage context. The main residual gap is error/behavior disclosure given the absence of annotations.

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 0%, but the sole parameter 'prodotto_ids' is self-describing and the description clarifies batch semantics ('per ciascun id'), telling the agent results are produced per id. This adds meaning the bare schema does not, though it could say what happens for absent ids.

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 ('SEO status of a selection of products in a single call') and explicitly contrasts with the sibling leggi_seo_prodotto by saying it returns the same content per each id. An agent can tell this is the batch variant of a single-product reader without opening any schema.

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

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

Gives concrete usage context: it is meant for the plugin's 'ottimizza SEO' button and works on products loaded before the plugin, not just those just created with scansiona_cartella_prodotti. It stops short of an explicit when-not or naming the single-product alternative as the choice for one id, so it is clear context without explicit 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?

With no annotations at all, the description carries the full burden, and it does disclose the payload contents (SEO title, meta description, focus keyword, plus title/description/price), which is meaningful since there is no output schema. However, it says nothing about behavior for a missing/invalid product_id, whether it is strictly read-only, or any auth/rate constraints, so key traits remain undisclosed.

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

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

A single compact sentence, front-loaded with the returned SEO fields and then the extra context fields. No filler; the parenthetical lists are dense but each item earns its place by documenting the return shape in the absence of 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?

For a one-parameter read tool with no output schema and no annotations, the description is close to sufficient: it enumerates the return fields and states the motivating use case. The remaining gap is error/edge-case behavior and cross-referencing the sibling tools, which for this level of complexity is a minor omission.

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

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

Schema coverage is 0% — prodotto_id has no description in the schema — and the description never explains the identifier, its format, or where to obtain it. The parameter name is self-explanatory and the description's 'di un prodotto' framing confirms it takes a single product, but no added semantics beyond that.

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 pairs a specific verb ('leggi' / stato) with a specific resource ('SEO di un prodotto') and even enumerates the fields returned (SEO title, meta description, focus keyword), so an agent knows exactly what it gets back. It implicitly scopes to a single product, distinguishing it from the plural sibling leggi_seo_prodotti_selezionati, but it never names that sibling explicitly.

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

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

The phrase 'come contesto per scrivere i nuovi testi' hints at the intended workflow (read current SEO before writing an update, presumably via aggiorna_seo_prodotto), but the guidance is implied rather than stated. There is no explicit when-to-use vs when-not, and no mention of choosing between this and leggi_seo_prodotti_selezionati or lista_stato_seo_prodotti.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the 200-record cap, that totale_trovati counts beyond `limite`, that only city is returned as personal data, that date filters intersect, and that dates use the site timezone. The remaining gap is no statement about pagination/offset mechanics for retrieving records past 200.

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 a one-line summary, then parameter-by-parameter lines that each add distinct information with no repetition. It runs long for a list tool, but nearly every clause earns its place; a slightly tighter grouping of the date parameters would improve it.

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

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

No output schema and no annotations, so the description must supply return shape and safety context — and it does, naming the returned fields (numero, stato, data, totale, pagamento, citta, prodotti), the privacy boundary, and the truncation behavior. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 0% and the description compensates fully: it enumerates the valid `stato` slugs and warns that 'evaso' is not one, defines `ultime_ore` and `piu_vecchi_di_ore` with an example, specifies the accepted date formats and inclusive end-of-day behavior for `da`/`a`, and defines `ordina` values. Even `limite` is anchored by the stated 200 maximum.

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

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

Opens with a specific verb+resource ('Elenco ordini WooCommerce') plus its two filtering axes, and explicitly routes detail lookups to dettaglio_ordine. An agent can distinguish it from the sibling without opening the schema.

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

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

Explicitly says 'Per i dettagli di un ordine usa dettaglio_ordine', establishing the boundary with the most confusable sibling. It does not, however, address when to prefer report_vendite_prodotti or the other list tools, so the routing is partial but useful.

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?

No annotations are provided, so the description carries full burden. It implies a safe read operation and discloses which fields are returned, but says nothing about pagination behavior when `limite` is exceeded, permissions/auth, or result ordering.

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

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

Two tight sentences with zero waste; the core purpose is front-loaded and the parameter note follows immediately.

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 (though the description helpfully lists them). The one real gap is `limite`/pagination semantics, which an agent needs to call the tool predictably; otherwise adequate for a simple read-only list.

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

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

Schema coverage is 0% and the description fully clarifies `ricerca` (substring match, case-insensitive, empty means all). It says nothing about `limite`, leaving half of the parameters undocumented in both schema and 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?

States a specific verb (Elenca) and resource (prodotti WooCommerce via REST) and even names the returned fields (titolo, sku, prezzo, scorte). It does not explicitly distinguish itself from filtered siblings like prodotti_in_bozza or prodotti_sotto_scorta, though 'vuoto = tutti' hints it is the unfiltered listing.

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 semantics of `ricerca` (substring, case-insensitive, empty = all products), which implies when to use it for a full listing. However it never names alternatives or exclusion conditions versus the many sibling product tools, leaving routing 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only overview and specifies included fields and product scope, but it does not disclose pagination behavior, performance implications of scanning all products, or permission requirements.

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

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

The description is front-loaded with the core purpose and then adds useful context about optimizing the catalog. It is reasonably concise, though slightly verbose and could be tightened.

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 zero parameters, full schema description coverage, and an output schema, the description provides enough context to call the tool correctly. It explains scope, included SEO fields, and the intended analysis use case.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. Baseline is 4; no additional parameter guidance is needed.

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

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

The description states a specific resource and scope: an SEO overview of all published or draft products, including whether SEO title and meta description are set or missing, their lengths, status, and creation date. The phrase 'tutti i prodotti pubblicati o in bozza' distinguishes it from single-product siblings such as leggi_seo_prodotto and draft-only siblings such as prodotti_in_bozza.

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

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

It gives a clear use case: starting an SEO optimization of the catalog and distinguishing newly added products from the consolidated catalog. It does not explicitly name alternatives or say when not to use it, but the intended context is clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses that nothing is persisted ('senza salvare'), that it drives the browser rather than the DB, and that a human-visible screenshot gates the change. It leaves out what happens to a pending modification if neither confirm nor abort is called, and whether the operation is repeatable.

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?

Short and front-loaded: the action is in the first sentence and the safety rationale and next steps follow. Line breaks are a bit awkward and one clause ('così l'utente puo' controllare lo screenshot') is slightly redundant with the 'sensibile' framing, but almost nothing is wasted.

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

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

For a sensitive two-step mutation with no annotations and no output schema, the description covers the staging model and the required next call, which is the core need. It is silent on what the tool returns (a pending-modification handle? the screenshot?) that the follow-up tool presumably consumes, which matters for chaining correctness.

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 0%, so the description must compensate and it largely does not: 'nuovo_prezzo_regolare' is typed as a string with no indication of format (decimal point vs comma, currency, thousands separators), which is a realistic failure mode for a price field. 'prodotto_id' is only implied by the noun 'prodotto'; no hint on where to obtain a valid 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?

States a specific verb and resource ('Compila il nuovo prezzo regolare di un prodotto in wp-admin') and immediately scopes it as non-committal ('senza salvare'), which distinguishes it from applica_aggiornamento_prezzi and conferma_modifica_in_corso. An agent can identify exactly what this does without opening the schema.

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

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

Gives an explicit operating condition ('Operazione sensibile: usa il browser... così l'utente puo' controllare lo screenshot prima che la modifica diventi effettiva') and prescribes the mandatory follow-up branching ('Dopo questo tool chiama conferma_modifica_in_corso oppure annulla_modifica_in_corso'). The when-to-use and what-to-do-next are both spelled out with named siblings.

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?

No annotations are provided, so the description must carry the behavioral load. It usefully discloses ordering (most recent first) and the draft-only filter, and the read-only nature is implied, but it says nothing about pagination, result limits, or permission requirements.

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

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

Two short clauses, front-loaded with the resource definition and filter before the ordering note. No wasted words.

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 and zero parameters, return-shape explanation is unnecessary. The description supplies the filter, ordering, and purpose; only edge-case behavior (empty list, volume limits) is unaddressed.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies.

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

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

States a specific resource and scope: draft products created via crea_prodotto that are not yet published, ordered most-recent-first. This clearly separates it from the generic lista_prodotti sibling, though it doesn't explicitly name that sibling as the 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?

The phrase 'promemoria di cosa resta da rivedere su wp-admin' implies the usage context (review queue), and referencing crea_prodotto hints at provenance, but there is no explicit statement of when to use this over lista_prodotti or lista_stato_seo_prodotti.

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

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

With no annotations, the description carries the burden well: it discloses result ordering (out-of-stock first, then ascending stock) and an important data-quality caveat that products without active stock management only report status, not a reliable stock count. It does not mention pagination or result limits, which is a smaller 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 scope and caveat before the ordering and use-case rationale. No filler, though it could be tighter.

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. The description covers scope, ordering, and the stock-management caveat; only the read-only nature and any result limits are left implicit.

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

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

Schema coverage is 0% and the single parameter only shows a default of 5, so the description must compensate. It does so by explaining that `soglia` is the stock threshold below which products are returned, which is more than the bare 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 concrete verb-less but clear purpose: products that are sold out or have stock below `soglia`, with an explicit scope caveat about WooCommerce stock management. An agent can distinguish it from `lista_prodotti`, though no sibling is named directly.

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 closing clause 'utile per capire cosa rifornire con più urgenza' implies the use case (restocking prioritization), but there is no explicit when-to-use versus when-not guidance and no named alternative among the many product-listing siblings.

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?

No annotations are provided, so the description carries the full burden. It does disclose the actual effect (site cache invalidation) and that this duplicates behavior baked into other write tools, which is meaningful context. However, it says nothing about permissions, whether the purge is global or partial, expected latency/impact, or what the call returns.

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 action is front-loaded in the first clause, and the parenthetical plus the second sentence each add distinct value (redundancy with write tools; the symptom that motivates manual use). Slightly verbose phrasing but nothing extraneous.

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

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

For a no-parameter, no-output-schema utility tool with no annotations, the description covers what it does, why it exists, and when to reach for it. The remaining gap is feedback behavior — whether success/failure is reported — but the essentials an agent needs to select and call it are present.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. The description correctly implies no input is needed by describing an unconditional manual purge.

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 ('Invalida manualmente la cache del sito') and clarifies its relationship to the write tools that invoke the same procedure automatically. It is clear what the tool does, though it doesn't differentiate itself from any named sibling beyond the implicit 'the others are automatic'.

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

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

Gives an explicit use condition: use it when something was modified outside these tools and the frontend still serves stale content. It also signals the inverse case by noting the write tools already purge automatically, implying it's redundant after normal write operations. No alternative tool is named, which keeps it 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?

With no annotations, the description carries the burden. It usefully discloses a non-obvious behavioral trait: the never-sold list covers the entire store history rather than the selected periodo. However it does not state the read-only nature explicitly, the currency/rounding of net revenue, result size, or whether the report is expensive to compute.

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 what the report contains, followed by the constrained parameter values. No filler; the parenthetical about full store history earns its place by clarifying scope.

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 report with no output schema and no annotations, the description covers the return payload (quantities, net revenue, zero-sales products) and the parameter domain. Missing only marginal details such as currency and how period boundaries are applied.

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

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

The single `periodo` parameter has 0% schema coverage and no enum in the schema, so the description's enumeration of the four allowed values is essential and fully compensates. It omits only that the default is "1_mese", which the schema already declares.

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 (sales report per product) and enumerates the contents: best sellers with quantity and net revenue, plus published-but-never-sold products. An agent can tell this is an analytics/report tool rather than a listing tool like lista_prodotti, though no sibling is named explicitly.

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

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

Usage is only implied by the nature of the tool — asking for a sales report. There is no statement of when to prefer this over lista_prodotti or lista_ordini, nor of any prerequisites (e.g. whether orders must exist, or whether the store must be connected).

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

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

With no annotations, the description carries the full burden and does well: it discloses what is destroyed (table row plus history), that local texts on the user's machine are deleted by default via `anche_testi_locali`, and the downstream consequence that controlla_somiglianza can no longer compare against that site until re-analysis. It also states what is NOT touched (products, already-written SEO fields), but omits reversibility/undo and what the call returns.

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

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

Purpose is front-loaded in the first clause, followed by side effects and then the usage restriction — a sensible order with no filler sentences. The awkward mid-sentence line breaks and slight repetition of the default flag cost a point.

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

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

For a destructive 2-parameter tool with no annotations and no output schema, the description covers scope, defaults, side effects, exclusions, and cross-tool impact. The remaining gap is return-value/confirmation behavior, which nothing else in the structured data supplies.

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

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

Schema coverage is 0%, so the description must compensate, and it does for both parameters: `sito` is explained as the name as shown in the table (with an example, "tomatosmartphone.it") or the address, and `anche_testi_locali` is described as default-on with its real effect on local files. What is missing is any note on accepted formats/aliases beyond the example.

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

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

States a specific verb and resource — removing an analyzed site from the «Concorrenti e confronto» table of the plugin's SEO tab, including its history. The named table and the explicit scope make it easily separable from siblings like analizza_seo_sito and controlla_somiglianza.

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 hard usage gate — use ONLY on explicit user request, and tell the user which site is being removed — plus a concrete motivation example (the report was useless). It does not name an alternative tool for the closely related task of clearing only local texts, which keeps it from 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?

With no annotations, the description carries the full burden and does so: it discloses destructive overwrite of current texts, the snapshot-rotation rule (the version left behind becomes 'precedente', so rollback is always possible), that never-modified products are left alone, the per-id outcome values, and the side effect of invalidating the site cache.

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

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

Front-loads the action, then the version semantics, the overwrite warning, and the return values in a logical order. Density is high, though the version explanation is somewhat verbose and could be tightened without losing meaning.

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

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

No output schema exists, yet the description enumerates all four possible per-id outcomes, so the agent knows exactly what a call returns. Combined with the cache-invalidation note and the irreversibility caveat, nothing needed to invoke it safely 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 0%, so the description must supply meaning, and it explains the 'versione' parameter's two accepted values and their semantics thoroughly. 'prodotto_ids' is only implicitly covered ('uno o più prodotti', per-id results), so the id format is left to the schema.

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

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

States a specific verb and resource (restore SEO title, meta description and focus keyword for one or more products) and explains the two restore targets, 'base' and 'precedente'. It is clearly distinguishable from the sibling aggiorna_seo_prodotto, which writes rather than restores.

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

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

Explicitly says 'Usalo solo su richiesta dell'utente: sovrascrive i testi attuali', naming the precondition and the risk. It also closes off a plausible alternative ('Non esiste un tool per ridefinire la base: lo fa solo l'utente dalla tab SEO'), removing a dead-end the agent might otherwise explore.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not say whether the operation is side-effect free, how the 'formale' flag changes output, or what the returned greeting looks like. For a zero-annotation tool this is a meaningful gap, even for a simple operation.

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

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

A single efficient sentence with no wasted words and no awkward framing. It is appropriately sized for a trivial tool, though it could have spent a few more words on the 'formale' parameter instead of nothing.

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 format needn't be explained, but with 0% schema coverage the description still leaves 'formale' entirely undefined. For a two-parameter tool, omitting the semantic effect of half the inputs is incomplete.

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 0%, so the description must compensate for two undocumented parameters. It only loosely implies 'nome' via 'persona indicata' and says nothing about 'formale', which materially changes the output format (formal vs informal greeting).

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: it returns a greeting for the indicated person. The purpose is unambiguous and trivially distinguishable from the catalog/SEO/order siblings. It does not, however, describe how the name is incorporated or what kind of greeting is produced.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. Being a trivial greeting tool lowers the stakes, but the description still offers no usage context at all.

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

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

With no annotations, the description carries the burden and does well: it declares read-only behavior, states existing products are ignored, and describes the payload returned for new products (category, image paths, raw .txt text). It omits failure modes (invalid path, unreadable folder, missing .txt) and any permission/filesystem-access notes.

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 the constraint, then the next-step instructions; nearly every sentence earns its place. Slightly dense parenthetical phrasing costs it a perfect score.

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

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

No output schema exists, so the description rightly explains what is returned (category, image paths, raw text) and that existing products are skipped. Minor gaps remain: whether existing products are listed or merely counted, and the shape of the returned collection.

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 0% and the only parameter has just a title ('Percorso Cartella'), so the description must compensate. It does partially by implying the expected directory layout, but it never clarifies whether percorso_cartella is the root containing category folders or a single category folder, nor absolute vs relative path.

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 precise verb and resource: it compares a local folder structured as `<Categoria>/<Prodotto>/` (photos + .txt) against the WooCommerce catalog to separate existing from new products. The scope is explicit and distinguishable from siblings like lista_prodotti or crea_prodotto.

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

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

Explicitly says what it does NOT do ('Non crea né modifica nulla') and prescribes the follow-up workflow: extract price/description from the raw .txt, then call crea_prodotto for each new product. It also anchors the intended trigger (the plugin's 'carica prodotti' button), leaving little 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?

No annotations are provided, so the description carries the full disclosure burden, and it discloses almost nothing: no mention of precision, rounding, handling of very large numbers, or what the sum is returned as. The existence of an output schema covers the return shape, but the behavioral profile of a pure computation tool is otherwise undocumented.

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

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

A single short sentence with zero waste and the operation front-loaded. It is efficient, though the brevity shades into under-specification rather than disciplined conciseness.

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 tool is trivial and an output schema exists, so an agent can call it correctly without much prose. Still, with no annotations and 0% parameter coverage, the description could have cheaply confirmed operand meaning and numeric behavior; it stops at the minimum.

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 0% — the parameters are bare 'A' and 'B' with only a numeric type. The phrase 'due numeri' implies both parameters are the addends, which is a small amount of meaning, but it does not say which is which (harmless for addition) or what units/precision are expected.

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 the operation (addition) and the operand count (two), which is enough for an agent to know what the tool does. However, 'Somma due numeri' largely restates the tool name 'somma' and adds no differentiation from siblings — though none of the listed siblings perform arithmetic, so differentiation is less critical here.

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

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

There is no guidance on when to use this tool, when not to, or what alternatives exist. Given the surrounding catalogue of e-commerce/SEO tools, even a note that this is a generic arithmetic utility unrelated to the catalogue workflow would help the agent place it.

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